Webhooks API
LeadPattern Webhooks API: 11 endpoints with request parameters, response schemas, error codes and cURL, Node.js and Python examples.
POSTRegister Webhook
/v2/webhook/registerRegister an endpoint to receive real-time event notifications. Use https:// — http:// is accepted, but deliveries (payloads, custom headers, credentials) are then unencrypted and the response includes a warnings array saying so. Private and internal addresses are rejected with 400. Signing is opt-in on the public API (recommended): pass generateSecret: true and the response contains a generated signing secret — shown only once, so store it immediately — or pass your own secret (16–128 chars). Without either, deliveries are unsigned. See the Webhooks Guide for verification. Deliveries are always a JSON POST; optional custom headers and a Bearer/Basic Authorization header are sent with each one. Payloads include waId (phone number) for standard contacts, or bsuid + username (Business-Scoped User ID) for opted-in contacts that have not shared their phone number.GETList Webhooks/v2/webhook?page=1&limit=10Retrieve all registered webhooks for this project. Custom header values and authorization credentials are always masked. Inactive webhooks carry a disabledReason: manual, plan_limit, or failing (auto-disabled after 50 consecutive failed deliveries).GETGet Webhook/v2/webhook/:webhookIdRetrieve one webhook, including its delivery health (isActive, disabledReason, failureCount, lastFailureAt). Header values and credentials are masked; the signing secret is never returned (hasSecret tells you one is set).PUTEdit Webhook/v2/webhook/:webhookIdUpdate the name, URL, event subscriptions, custom headers, authorization or signing secret of a registered webhook. Send at least one field. Omit headers / authorization to keep the stored values (send headers: null to remove all headers, authorization: null or { type: "NONE" } to remove authorization) — except when the URL changes: saved headers and credentials are never sent to a new URL, so re-send them in full or they are dropped. Send secret to set your own signing secret, or removeSecret: true to stop signing deliveries; omit both to keep the current secret. Use Rotate Signing Secret to get a new generated secret.PATCHToggle Webhook/v2/webhook/:webhookId/togglePause an active webhook, or re-activate an inactive one. Re-activating resets the failure counter — use it after fixing an endpoint that was auto-disabled (disabledReason: failing). Returns 402 if re-activating would exceed your plan's webhook limit.POSTRotate Signing Secret/v2/webhook/:webhookId/rotate-secretGenerate a new signing secret for a webhook. The new secret is returned once in data.secret — store it immediately. If the webhook already had a secret, the old one stays valid for 24 hours (until data.previousSecretValidUntil): during that window every delivery carries signatures made with both secrets — X-Webhook-Signature / X-Webhook-Signature-V2 (new) and X-Webhook-Signature-Previous / X-Webhook-Signature-V2-Previous (old) — so you can switch your receiver over without dropping deliveries. Calling it on an unsigned webhook turns signing on (no grace period, previousSecretValidUntil: null).POSTSend Test Webhook/v2/webhook/:webhookId/testQueues a sample payload (event: "test") for delivery to this webhook using its saved URL, headers, authorization and secret, bypassing event-subscription matching. The response's data.eventId is the test event's id (also sent as X-Webhook-Id) — find its attempts in the delivery logs. The webhook must be active, and tests are limited to one per webhook every 10 seconds.GETWebhook Delivery Logs/v2/webhook/:webhookId/logs?page=1&limit=20Retrieve delivery history for a registered webhook — one row per attempt, with the event id, HTTP status code, attempt number and error. Pass includePayload=true to also get the delivered JSON payload; it is stored on attempt 1 of each event only (later attempts return payload: null). Logs are kept for 30 days.POSTRedeliver Webhook Event/v2/webhook/:webhookId/logs/:eventId/redeliverSend one past delivery again — the original payload with the same event id (X-Webhook-Id) and a fresh signature — as a single attempt. Use it after fixing your endpoint or to replay an event your system lost. The result appears in the delivery logs with redelivery: true. The webhook must be active, payloads are kept for 30 days, and each event can be redelivered once every 30 seconds.POSTEvent Payload Format/your-registered-webhook-urlThis is what LeadPattern POSTs to your registered endpoint when an event fires: an envelope { id, event, timestamp, data }. id is unique per event and identical across retries (also sent as X-Webhook-Id) — use it to deduplicate. Respond with any 2xx within 10 seconds. For BSUID contacts (opted-in users who have not shared their phone number) the contact carries bsuid and username instead of waId and phone. See the Webhooks Guide for signature verification, delivery rules and an example of every event.DELETEDelete Webhook/v2/webhook/:webhookIdPermanently deactivate and delete a registered webhook.