Skip to main content
POST
/
organizations
/
{organizationId}
/
webhooks
Create a new webhook
curl --request POST \
  --url http://sandbox.mintlify.com/organizations/{organizationId}/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com/webhooks",
  "events": [
    "organization.created",
    "organization.updated"
  ]
}
'
Creates a webhook endpoint for receiving events. Only OWNERS and ADMINS can create webhooks.

​
Authentication

This endpoint requires authentication via Bearer token:
  • Authorization: Bearer <token>

​
Path Parameters

ParameterTypeRequiredDescription
organizationIdstring (UUID)YesOrganization ID

​
Request Body

FieldTypeRequiredDescription
urlstringYesWebhook endpoint URL (must be valid HTTPS URL)
eventsarrayYesArray of event types to subscribe to

​
Available Events

Subscribe to any of these events:
  • Organization: organization.created, organization.updated, organization.deleted
  • Members: member.added, member.removed, member.role_updated
  • Invites: invite.created, invite.accepted, invite.cancelled
  • OAuth: oauth_app.created, oauth_app.revoked
  • Webhooks: webhook.created

​
Permissions

Only OWNERS and ADMINS can create webhooks.

​
Example Request

curl -X POST http://localhost:3001/api/organizations/550e8400-e29b-41d4-a716-446655440000/webhooks \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks",
    "events": ["organization.created", "member.added"]
  }'

​
Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/webhooks",
  "events": ["organization.created", "member.added"],
  "isActive": true,
  "secret": "whsec_1234567890abcdef",
  "createdAt": "2025-01-26T10:00:00Z",
  "updatedAt": "2025-01-26T10:00:00Z"
}
⚠️ Important: Save the secret value - it’s only returned once and used for signature verification.

​
Webhook Payload

Your endpoint will receive POST requests with this format: 
{
  "event": "member.added",
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "acme-corp",
    "name": "Acme Corp"
  },
  "data": { ... },
  "timestamp": "2025-12-26T10:00:00Z"
}

​
Signature Verification

All webhook requests include an HMAC SHA-256 signature in the X-Webhook-Signature header for verification. 
const crypto = require('crypto')

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret)
  const digest = hmac.update(payload).digest('hex')
  return digest === signature
}

​
Retry Logic

Failed webhook deliveries are retried up to 3 times with exponential backoff (1s, 5s, 30s).

​
Common Errors

​
400 Bad Request

Invalid input data. 
{
  "statusCode": 400,
  "message": ["url must be a valid URL", "events must be an array"]
}

​
401 Unauthorized

Authentication required. 
{
  "statusCode": 401,
  "message": "Authentication required. Provide a valid bearer token."
}

​
403 Forbidden

Only owners and admins can create webhooks. 
{
  "statusCode": 403,
  "message": "Access denied. Only owners and admins can create webhooks."
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
organizationId
string
required

Body

application/json
​
url
string
required

Webhook endpoint URL

Example:

"https://example.com/webhooks"

​
events
enum<string>[]
required

Events to subscribe to

Available options:
organization.created,
organization.updated,
organization.deleted,
member.added,
member.removed,
member.role_updated,
invite.created,
invite.accepted,
invite.cancelled,
oauth_app.created,
oauth_app.revoked,
webhook.created
Example:
[
  "organization.created",
  "organization.updated"
]

Response

Webhook created successfully. Returns webhook configuration with signing secret.