Webhook endpoints

#The WebhookEndpoint object

A webhook endpoint of your organization and its state. The full URL is not returned because its path can be a secret: only the host. Additional header values are not returned either, only their names.

Attributes

• objectstring
  Object type, always webhook_endpoint.
• idstring (uuid)
  Endpoint id.
• statusstring
  active receives events, paused is paused, disabled was turned off: by itself or by a 410 from the receiver. Values: active paused disabled
• disabled_reasonstring or null
  Why the endpoint is off or paused: gone (the receiver answered 410), failing_72h (errors for more than 3 days), plan (the plan has no webhooks), other. null for a working endpoint. Values: gone failing_72h plan other
• hoststring
  Host of the receiver. Up to 253 characters.
• descriptionstring or null
  Description from the app, or null. Up to 500 characters.
• event_typesarray of string
  Event types the endpoint receives. Up to 20 items.
• workspace_idsarray of string or null
  Workspaces whose events the endpoint receives. null: all workspaces. Up to 50 items.
• campaign_idsarray of string or null
  Campaigns whose events the endpoint receives. null: all campaigns. Up to 500 items.
• include_message_textboolean
  Whether the lead's reply text is sent.
• header_namesarray of string
  Names of additional headers, without values. Up to 5 items.
• failing_sincestring (date-time) or null
  Since when the endpoint does not accept events, or null if the last attempt succeeded.
• consecutive_failuresinteger
  Failed attempts in a row.
• last_success_atstring (date-time) or null
  Time of the last successful delivery, or null.
• versioninteger
  Version of the endpoint settings. Grows with every change.
• created_atstring (date-time)
  When the endpoint was added.
• updated_atstring (date-time)
  When the endpoint settings last changed.
• deliveriesobject
  Delivery summary.
  Child attributes

  • pendinginteger
    How many events wait to be sent.
  • succeeded_24hinteger
    Delivered in the last 24 hours.
  • failed_24hinteger
    Not delivered in the last 24 hours.
  • last_finished_atstring (date-time) or null
    When the last delivery finished, or null.
  • last_status_codeinteger or null
    Receiver's response code for the last delivery, or null.
  • last_error_classstring or null
    Class of the last error: invalid_url, dns, ssrf_blocked, connect, tls, timeout, http, payload_too_large, unknown or null. Values: invalid_url dns ssrf_blocked connect tls timeout http payload_too_large unknown

#The WebhookDelivery object

One delivery of an event to a webhook endpoint. No lead data: the event feed returns the event itself by event_id.

Attributes

• objectstring
  Object type, always webhook_delivery.
• idstring (uuid)
  Delivery id.
• endpoint_idstring (uuid)
  Webhook endpoint.
• event_idstring
  Event id: the same as in the webhook-id header and in the event feed. Format ^evt_[a-f0-9]{32}$.
• event_typestring or null
  Event type, webhook.test for a test event, unknown for an unknown one, or null if the event is gone. Values: lead.first_message_sent lead.replied message.received lead.status_changed campaign.status_changed account.status_changed message.sent message.delivery_unknown webhook.test unknown
• statusstring
  pending waits, delivering is being sent, succeeded delivered, failed not delivered, cancelled cancelled. Values: pending delivering succeeded failed cancelled unknown
• cancel_reasonstring or null
  Why the delivery was cancelled: scope_changed, endpoint_deleted, expired, other. null if not cancelled. Values: scope_changed endpoint_deleted expired other
• attemptinteger
  Number of attempts.
• next_attempt_atstring (date-time) or null
  When the next attempt is due. Only for pending, otherwise null.
• last_status_codeinteger or null
  Receiver's response code for the last attempt, or null.
• last_error_classstring or null
  Error class of the last attempt, or null. Values: invalid_url dns ssrf_blocked connect tls timeout http payload_too_large unknown
• last_duration_msinteger or null
  Duration of the last attempt in milliseconds, or null.
• created_atstring (date-time)
  When the event was queued for delivery.
• finished_atstring (date-time) or null
  When the delivery finished, or null.

#List webhook endpoints

GET/v1/webhook-endpoints

Webhook endpoints of your organization and their state: whether they accept events, since when they fail, the last error and deliveries in the last 24 hours, oldest first. Needs a key for all workspaces and campaigns: webhooks belong to the whole organization.

Permission

webhooks:read

Request weight

1

Parameters

• limitinteger, queryoptional
  Number of objects to return per page. From 1 to 100. Defaults to 50.
• cursorstring, queryoptional
  The next_cursor value from the previous response. Other filters must match the first request.
• statusstring, queryoptional
  Only endpoints in this state. Values: active paused disabled

Response

A list: object, data (an array of WebhookEndpoint objects), has_more, next_cursor. See Pagination.

Endpoint-specific errors

• cursor_mismatch: The cursor is corrupted, was issued for a different route or filters, or the key's permissions and scope have changed.
• scope_required: The key does not permit the operation. A command requires its kind permission.
• not_found: The object was not found or is outside the key's scope. An unknown path also returns 404.
• cursor_expired: The cursor expired: 15 minutes for lists, 30 days for the event feed.

Common errors are described in Errors.

#Get a webhook endpoint

GET/v1/webhook-endpoints/{id}

One webhook endpoint by id. A deleted endpoint gives 404.

Permission

webhooks:read

Request weight

1

Parameters

• idstring (uuid), pathrequired
  Webhook endpoint id.

Response

Returns a WebhookEndpoint object.

Endpoint-specific errors

• scope_required: The key does not permit the operation. A command requires its kind permission.
• not_found: The object was not found or is outside the key's scope. An unknown path also returns 404.

Common errors are described in Errors.

#Delivery log

GET/v1/webhook-endpoints/{id}/deliveries

Event deliveries to one endpoint, newest first: state, attempts, response code and error. Helps find out why your CRM did not get an event. The event feed returns the event itself by event_id.

Permission

webhooks:read

Request weight

2

Parameters

• idstring (uuid), pathrequired
  Webhook endpoint id.
• limitinteger, queryoptional
  Number of objects to return per page. From 1 to 100. Defaults to 50.
• cursorstring, queryoptional
  The next_cursor value from the previous response. Other filters must match the first request.
• statusstring, queryoptional
  Only deliveries in this state. Values: pending delivering succeeded failed cancelled

Response

A list: object, data (an array of WebhookDelivery objects), has_more, next_cursor. See Pagination.

Endpoint-specific errors

• cursor_mismatch: The cursor is corrupted, was issued for a different route or filters, or the key's permissions and scope have changed.
• scope_required: The key does not permit the operation. A command requires its kind permission.
• not_found: The object was not found or is outside the key's scope. An unknown path also returns 404.
• cursor_expired: The cursor expired: 15 minutes for lists, 30 days for the event feed.

Common errors are described in Errors.