API reference

Webhook endpoints

Create a webhook endpoint#

POST/v1/webhook_endpointsScopewebhooks:write

Registers a URL to receive events. The endpoint belongs to the mode of the API key: an endpoint created with a test key receives test-mode events only.

The response contains the signing secret. Store it; it is not returned again except when you roll it.

An account can have up to 500 endpoints per mode, so that every Zap, workflow or scenario can own one. An integration that creates endpoints for its users sets source (and may keep its own IDs in metadata); such an endpoint is removed automatically after 30 days of uninterrupted failures. filters narrows the deliveries on our side. verification_token adds a static header for receivers that cannot verify the signature.

The URL must be public HTTPS: localhost, private and link-local addresses are refused with webhook_url_not_public.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Request body

urlstringRequired
Public HTTPS URL. Hosts that resolve to private or loopback addresses are rejected.
Up to 2048 characters
eventsarray of stringsRequired
Event types to subscribe to, or ["*"] for all.
Possible valuesmessage.sentmessage.deliveredmessage.readmessage.failedmessage.receivedchannel.connectedchannel.disconnectedbalance.lowpackage.exhaustedpackage.expiringcampaign.startedcampaign.pausedcampaign.completedcampaign.failed*
descriptionstringOptional
Optional note.
Up to 255 characters
filtersobjectOptional
Server-side filters. An event is delivered only when it matches every filter that is set; events that do not carry the filtered property (for example balance.low) always pass.
Show child attributesHide child attributes
- channel_idstringOptional
  Only events about this channel: messages on it, and its own channel.* events.
- directionstringOptional
  Only message events of this direction.
  Possible valuesoutboundinbound
metadataobjectOptional
Up to 20 string values for your own bookkeeping: a Zap ID, a workflow name.
Up to 20 keys
sourcestring or nullOptional
Name of the tool that owns the endpoint, as a lower-case slug (zapier, n8n, make). Set it when an integration creates endpoints on behalf of a user: the console groups by it, and abandoned endpoints are cleaned up.
verification_tokenstring or nullOptional
A static token of 16 to 255 printable characters, sent with every delivery in the OmniMessage-Verification-Token header. For receivers that cannot verify the HMAC signature. Write-only.
16 to 255 characters

Responses

201
The endpoint was created. secret is included. Webhook endpoint object.
400
Invalid body, an unknown event type, a URL that is not reachable from the internet (webhook_url_not_public), or the limit of endpoints per mode is reached (webhook_endpoint_limit_reached).
parameter_missing parameter_invalid invalid_json webhook_url_not_public webhook_endpoint_limit_reached
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The channel named in filters.channel_id does not exist in this account and mode.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/webhook_endpoints

Example

curl https://api.omnimessage.co/v1/webhook_endpoints \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/omni",
    "events": [
      "message.delivered",
      "message.failed",
      "message.received"
    ],
    "description": "Production delivery receipts"
  }'

Response · 201

{
  "id": "we_3kL9pQ2wE5rT8yU1iO4a",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://example.com/hooks/omni",
  "description": "Production delivery receipts",
  "events": [
    "message.delivered",
    "message.failed",
    "message.received"
  ],
  "status": "active",
  "filters": {},
  "metadata": {},
  "source": null,
  "created_by": {
    "type": "api_key",
    "id": "key_1qW4eR7tY0uI3oP6aS9d"
  },
  "has_verification_token": false,
  "created_at": "2026-10-02T11:15:00.000Z",
  "secret": "whsec_Zk8vQ2mX5cB7nL0pR3tY6wA9dF1gH4jK"
}

List webhook endpoints#

GET/v1/webhook_endpointsScopewebhooks:read

Returns the webhook endpoints of the key mode, newest first. The signing secret is not included.

Query parameters

limitintegerOptional
Number of objects to return, 1 to 100. Default 20.
starting_afterstringOptional
Cursor for the next page: the next_cursor of the previous response (the ID of its last object).

Responses

200
A page of webhook endpoints.
400
Bad request.
parameter_invalid
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/webhook_endpoints

curl https://api.omnimessage.co/v1/webhook_endpoints \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "object": "list",
  "data": [
    {
      "id": "we_3kL9pQ2wE5rT8yU1iO4a",
      "object": "webhook_endpoint",
      "mode": "live",
      "url": "https://example.com/hooks/omni",
      "description": "Production delivery receipts",
      "events": [
        "message.delivered",
        "message.failed",
        "message.received"
      ],
      "status": "active",
      "filters": {},
      "metadata": {},
      "source": null,
      "created_by": {
        "type": "api_key",
        "id": "key_1qW4eR7tY0uI3oP6aS9d"
      },
      "has_verification_token": false,
      "created_at": "2026-10-02T11:15:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a webhook endpoint#

GET/v1/webhook_endpoints/{id}Scopewebhooks:read

Returns one webhook endpoint. The signing secret is not included.

Path parameters

idstringRequired
Webhook endpoint ID.

Responses

200
The endpoint. Webhook endpoint object.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

GET/v1/webhook_endpoints/{id}

curl https://api.omnimessage.co/v1/webhook_endpoints/we_3kL9pQ2wE5rT8yU1iO4a \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "we_3kL9pQ2wE5rT8yU1iO4a",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://example.com/hooks/omni",
  "description": "Production delivery receipts",
  "events": [
    "message.delivered",
    "message.failed",
    "message.received"
  ],
  "status": "active",
  "filters": {},
  "metadata": {},
  "source": null,
  "created_by": {
    "type": "api_key",
    "id": "key_1qW4eR7tY0uI3oP6aS9d"
  },
  "has_verification_token": false,
  "created_at": "2026-10-02T11:15:00.000Z"
}

Update a webhook endpoint#

PATCH/v1/webhook_endpoints/{id}Scopewebhooks:write

Changes the URL, the note, the subscribed events or the status. Only the fields you send are changed. Setting status to active re-enables an endpoint that was disabled automatically and resets its failure count.

Path parameters

idstringRequired
Webhook endpoint ID.

Request body

urlstringOptional
New URL.
Up to 2048 characters
descriptionstring or nullOptional
Replaces the note. null clears it.
Up to 255 characters
eventsarray of stringsOptional
Replaces the subscribed event types.
Possible valuesmessage.sentmessage.deliveredmessage.readmessage.failedmessage.receivedchannel.connectedchannel.disconnectedbalance.lowpackage.exhaustedpackage.expiringcampaign.startedcampaign.pausedcampaign.completedcampaign.failed*
statusstringOptional
Set disabled to pause deliveries, active to resume or to re-enable an automatically disabled endpoint.
Possible valuesactivedisabled
filtersobjectOptional
Server-side filters. An event is delivered only when it matches every filter that is set; events that do not carry the filtered property (for example balance.low) always pass.
Show child attributesHide child attributes
- channel_idstringOptional
  Only events about this channel: messages on it, and its own channel.* events.
- directionstringOptional
  Only message events of this direction.
  Possible valuesoutboundinbound
metadataobjectOptional
Replaces the metadata.
Up to 20 keys
verification_tokenstring or nullOptional
Replaces the verification token. null removes it.
16 to 255 characters

Responses

200
The updated endpoint. Webhook endpoint object.
400
Bad request.
parameter_missing parameter_invalid invalid_json webhook_url_not_public
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

PATCH/v1/webhook_endpoints/{id}

Example

curl -X PATCH https://api.omnimessage.co/v1/webhook_endpoints/we_3kL9pQ2wE5rT8yU1iO4a \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "message.failed",
      "channel.disconnected"
    ]
  }'

Response · 200

{
  "id": "we_3kL9pQ2wE5rT8yU1iO4a",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://example.com/hooks/omni",
  "description": "Production delivery receipts",
  "events": [
    "message.failed",
    "channel.disconnected"
  ],
  "status": "active",
  "filters": {},
  "metadata": {},
  "source": null,
  "created_by": {
    "type": "api_key",
    "id": "key_1qW4eR7tY0uI3oP6aS9d"
  },
  "has_verification_token": false,
  "created_at": "2026-10-02T11:15:00.000Z"
}

Delete a webhook endpoint#

DELETE/v1/webhook_endpoints/{id}Scopewebhooks:write

Removes the endpoint. Pending retries for it are discarded.

Path parameters

idstringRequired
Webhook endpoint ID.

Responses

200
The endpoint was deleted.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

DELETE/v1/webhook_endpoints/{id}

curl -X DELETE https://api.omnimessage.co/v1/webhook_endpoints/we_3kL9pQ2wE5rT8yU1iO4a \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "we_3kL9pQ2wE5rT8yU1iO4a",
  "object": "webhook_endpoint",
  "deleted": true
}

Roll the signing secret#

POST/v1/webhook_endpoints/{id}/roll_secretScopewebhooks:write

Generates a new signing secret and returns it. The previous secret stops being used immediately, so deploy the new one right away; deliveries your server rejects in between are retried.

Path parameters

idstringRequired
Webhook endpoint ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Responses

200
The endpoint with its new secret. Webhook endpoint object.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/webhook_endpoints/{id}/roll_secret

curl -X POST https://api.omnimessage.co/v1/webhook_endpoints/we_3kL9pQ2wE5rT8yU1iO4a/roll_secret \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "we_3kL9pQ2wE5rT8yU1iO4a",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://example.com/hooks/omni",
  "description": "Production delivery receipts",
  "events": [
    "message.delivered",
    "message.failed",
    "message.received"
  ],
  "status": "active",
  "filters": {},
  "metadata": {},
  "source": null,
  "created_by": {
    "type": "api_key",
    "id": "key_1qW4eR7tY0uI3oP6aS9d"
  },
  "has_verification_token": false,
  "created_at": "2026-10-02T11:15:00.000Z",
  "secret": "whsec_N7bT4xK1mQ8wE5rY2uI9oP3aS6dF0gHj"
}

Send a test event#

POST/v1/webhook_endpoints/{id}/testScopewebhooks:write

Queues a webhook.test event for the endpoint, signed like any other delivery, whatever its event subscriptions. Returns the event that will be delivered. Use it to check connectivity and your signature verification.

Path parameters

idstringRequired
Webhook endpoint ID.

Headers

Idempotency-KeystringOptional
Unique string of up to 255 characters, such as a UUID. Repeating a request with the same key and body within 24 hours returns the stored response instead of performing the operation again.

Responses

200
The queued test event. Event object.
401
The API key is missing, invalid, revoked or expired.
api_key_missing api_key_invalid api_key_revoked api_key_expired
403
The API key is not allowed to make this request.
scope_missing ip_not_allowed account_suspended
404
The resource does not exist in this account and mode.
resource_missing
409
Conflict.
idempotency_key_in_use idempotency_key_reused
429
Too many requests. Wait for Retry-After seconds.
rate_limit_exceeded
500
Unexpected error on our side. Safe to retry with the same Idempotency-Key.
internal_error

POST/v1/webhook_endpoints/{id}/test

curl -X POST https://api.omnimessage.co/v1/webhook_endpoints/we_3kL9pQ2wE5rT8yU1iO4a/test \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response · 200

{
  "id": "evt_6hJ9kL2zX5cV8bN1mQ4w",
  "object": "event",
  "type": "webhook.test",
  "mode": "live",
  "created_at": "2026-10-05T09:30:02.900Z",
  "data": {
    "object": {
      "id": "we_3kL9pQ2wE5rT8yU1iO4a",
      "object": "webhook_endpoint",
      "mode": "live",
      "url": "https://example.com/hooks/omni",
      "description": "Production delivery receipts",
      "events": [
        "message.delivered",
        "message.failed",
        "message.received"
      ],
      "status": "active",
      "filters": {},
      "metadata": {},
      "source": null,
      "created_by": {
        "type": "api_key",
        "id": "key_1qW4eR7tY0uI3oP6aS9d"
      },
      "has_verification_token": false,
      "created_at": "2026-10-02T11:15:00.000Z"
    }
  }
}