Create a new webhook

Registers a new webhook endpoint for receiving real-time event notifications. The response includes a one-time HMAC-SHA256 signing secret — store it securely, as it cannot be retrieved again. All deliveries to this endpoint will include an X-Signature header signed with this secret. Failed deliveries are retried up to 3 times with exponential backoff. After 10 consecutive failures the webhook is automatically disabled.

Registers a new webhook endpoint for receiving real-time event notifications. The response includes a one-time HMAC-SHA256 signing secret — store it securely, as it cannot be retrieved again. All deliveries to this endpoint will include an `X-Signature` header signed with this secret. Failed deliveries are retried up to 3 times with exponential backoff. After 10 consecutive failures the webhook is automatically disabled.

Authentication

AuthorizationBearer

API Key in the format mk_live_<43-chars>. Obtain from the Dashboard or POST /auth/api-keys.

Request

This endpoint expects an object.

urlstringRequiredformat: "uri"

HTTPS endpoint URL that will receive webhook POST requests. Each delivery is signed with HMAC-SHA256 using the webhook secret.

eventslist of enumsRequired

List of event types to subscribe to. At least one event type is required.

numberIdslist of stringsOptional

Optional list of WhatsApp Business number IDs to filter events for. If omitted, events for all numbers are delivered.

contactslist of stringsOptional

Optional list of contacts (phone numbers or BSUIDs) to restrict deliveries to. If any webhook restricts a contact, ALL events for that contact go only to contact-restricted webhooks; default catch-all webhooks are bypassed for that contact.

Response

Default Response

idstring

Unique identifier of the webhook

urlstring

HTTPS endpoint URL that receives webhook POST requests

eventslist of strings

List of event types this webhook is subscribed to

numberIdslist of strings

List of number IDs this webhook is filtered to. Empty array means all numbers.

contactslist of strings

List of contacts this webhook is restricted to. Empty array means all contacts (catch-all).

activeboolean

Whether the webhook is currently active. Automatically set to false after 10 consecutive delivery failures.

createdAtstring

ISO 8601 timestamp when the webhook was created

secretstring

HMAC-SHA256 signing secret for verifying webhook payloads. Only returned on creation and secret rotation. Store it securely — it cannot be retrieved again.

failureCountdouble

Number of consecutive delivery failures. Resets to 0 on a successful delivery. Webhook is auto-disabled at 10.

lastStatusCodedouble or null

HTTP status code returned by the endpoint on the most recent delivery attempt

lastTriggeredAtstring or null

ISO 8601 timestamp of the most recent delivery attempt

updatedAtstring

ISO 8601 timestamp when the webhook was last updated

Errors

400

Bad Request Error

401

Unauthorized Error

1	curl -X POST https://api.muchaw.dev/api/webhooks/ \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"url": "https://webhooks.example.com/receive",
6	"events": [
7	"message.received"
8	]
9	}'

1	{
2	"id": "wh_9f8b7c6d-1234-4e56-8a9b-0c1d2e3f4a5b",
3	"url": "https://webhooks.example.com/receive",
4	"events": [
5	"message.received"
6	],
7	"numberIds": [
8	"123456789012345"
9	],
10	"contacts": [
11	"15551234567"
12	],
13	"active": true,
14	"createdAt": "2024-06-01T11:45:00Z",
15	"secret": "a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789abcdef0",
16	"failureCount": 0,
17	"lastStatusCode": 200,
18	"lastTriggeredAt": "2024-06-01T12:00:00Z",
19	"updatedAt": "2024-06-01T11:50:00Z"
20	}