Sign in

v1

latestOpenAPI 3.1.02026-07-26359254.7 MB
Webhooks

Create a webhook subscription

<small>Requires the webhooks:write scope (or a broader one that includes it).</small>

Creates a new webhook subscription for the authenticated user.

scope defaults to personal when omitted. team-scope subscriptions are accepted only when policy allows: any member may create them for public teams or organization mode; only the team owner may create them for private teams.

Attempting to create an organization-scope subscription is rejected with code: webHook.organizationScopeNotImplemented — the value is reserved for future use.

post/v3/webhooks

Request body

eventTypestring required

Event type this subscription should fire on. Must be one of the values returned by GET /v3/webhooks/events.

urlstring uri required

Absolute http/https URL that will receive the webhook payload.

scope'personal' | 'team' | 'organization'

Scope that determines which users' activity triggers the webhook.

  • personal — fires only for activity of the subscription owner.
  • team — fires for activity of any member of the owner's team. Creation requires the current user to be the team owner for private teams; anyone can create for public teams.
  • organization — reserved for future use. The API currently rejects creation/update with this value (errorCode: 5).
enabledboolean

Create the subscription in an enabled (firing) state. Defaults to true. After creation, toggle the state via the dedicated POST /v3/webhooks/{id}/enable and POST /v3/webhooks/{id}/disable endpoints.

Example request

{
  "eventType": "email_replied",
  "url": "https://example.com/hooks/reply",
  "scope": "personal",
  "enabled": true,
  "payloadConfig": {
    "includeEmailUrl": true,
    "includeEmailText": false,
    "includeProspectCustomFields": true
  }
}

Response

Webhook subscription created successfully.

idinteger

Unique identifier for the webhook subscription.

eventTypestring

Event type this subscription fires on. One of the values returned by GET /v3/webhooks/events.

urlstring uri

Absolute http/https URL that receives the webhook payload.

scope'personal' | 'team' | 'organization'

Scope that determines which users' activity triggers the webhook.

  • personal — fires only for activity of the subscription owner.
  • team — fires for activity of any member of the owner's team. Creation requires the current user to be the team owner for private teams; anyone can create for public teams.
  • organization — reserved for future use. The API currently rejects creation/update with this value (errorCode: 5).
enabledboolean

If false, the subscription does not fire. Toggle via the dedicated POST /v3/webhooks/{id}/enable and POST /v3/webhooks/{id}/disable endpoints — the state cannot be changed through PUT.

createdAtstring date-time

ISO-8601 timestamp (UTC) when the subscription was created.

Example response

{
  "id": 1823,
  "eventType": "email_replied",
  "url": "https://example.com/hooks/reply",
  "scope": "personal",
  "enabled": true,
  "createdAt": "2026-04-17T12:00:00+00:00",
  "payloadConfig": {
    "includeEmailUrl": true,
    "includeEmailText": false,
    "includeProspectCustomFields": true
  }
}