Create Webhook

We use webhooks to let your application know when events happen, such as receiving an SMS message. When the event occurs, the system makes an HTTP request (usually a POST) to the URL you configured for the webhook. The request will include details of the event such as the incoming phone number or the body of an incoming message.
Send the request body with a Content-Type of application/json. Parameters such as charset=utf-8 are accepted.
Repeating a create with the same url and filter returns the existing webhook with 200 OK instead of creating a duplicate, even when name or rate_limit differ. The url must match exactly (no trailing-slash or letter-case normalisation). Filters match regardless of key order or value order, and sender, status, message_ref and campaign_id values also match regardless of letter case; event_type values must still be the upper-case names listed below. To change an existing webhook, use PUT /v2/webhook/{id}.
An account can have at most 25 webhooks. When the account already has 25, creating a new one returns 409 Conflict; delete a webhook with DELETE /v2/webhook/{id} before creating another. Repeating a create that matches an existing webhook still returns 200 OK at the limit, because no new webhook is created.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
enum
deprecated

Type of event to subscribe to. Deprecated - use filter.event_type instead.

filter
object

Filter to apply to webhook events. The filters are applied differently based on the event type:

  • For status events (SMS_STATUS, MMS_STATUS, etc.): sender, status,
    message_ref, and campaign_id filters are applied to the status payload.
  • For LINK_HIT events: sender and message_ref filters are applied to
    the source_message in the link-hit payload.
  • For OPT_OUT events: sender and message_ref filters are applied to
    the source_message in the opt-out payload.
  • For inbound events (SMS_INBOUND, MMS_INBOUND, etc.): sender filter is
    applied to the recipient field (the sender address that received the inbound message),
    while message_ref and campaign_id filters are applied to last_message if available.
  • For sender events (SENDER_REGISTRATION_STATUS, SENDER_COMPLIANCE_STATUS): the sender
    filter is applied to the event's sender. They have no message status, message_ref or
    campaign_id, so a webhook that sets any of those filters receives no sender events.

Within each filter array (e.g., sender, status, message_ref), the conditions are combined using an OR logic. For example, if multiple senders are specified, the webhook will trigger if the event matches any of the specified senders. Between different filters (e.g., sender and status), the conditions are combined using an AND logic. For example, the webhook will trigger only if the event matches both the specified sender and the specified status.

string
required
length between 2 and 100

Name of the webhook

uri
required

Absolute https URL that accepts JSON encoded POST requests.
Any other scheme (http, ftp, wss) or a URL without a scheme is rejected with 400.

integer

Rate limit for your URL in requests per second. Max 10,000/sec. If set to 0 or not specified, the default system limit will be applied.

boolean
deprecated

Deprecated. Will be removed in a future version.

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json