WaConnect

API referenceWebhooks

Webhooks

Check whether your webhooks are active or paused.

Read-only access to your webhook endpoints and their health. Webhooks are added and edited in Settings → Developer settings → Webhooks; these endpoints let your software see whether its webhook is receiving events, so it can alert your team when it isn't.

The webhook object#

Webhookjson
{
  "id": "01a0f52b-7c1d-7e2f-9a3b-4c5d6e7f8a9b",
  "url": "https://booking.example.com/webhooks/waconnect",
  "description": "Booking app",
  "events": ["message.received", "message.status"],
  "numbers": ["01a0f44d-c969-75b1-955d-3841d817f711"],
  "status": "active",
  "pausedReason": null,
  "pausedAt": null,
  "failingSince": null,
  "lastDeliveryAt": "2026-10-08T14:02:11.000Z",
  "lastSuccessAt": "2026-10-08T14:02:11.000Z",
  "recentFailures": 0,
  "createdAt": "2026-10-01T10:00:00.000Z"
}

Fields

idstringrequired
The webhook's id.
urlstringrequired
Where events are sent.
descriptionstring | nullrequired
The description you gave it.
eventsstring[]required
The event types it receives.
numbers"all" | string[]required
"all", or the ids of the numbers whose events it receives.
statusactive | pausedrequired
paused: it receives nothing until someone resumes it in Developer settings.
pausedReasonstring | nullrequired
Why it's paused: by a team member, or automatically after 3 days of failed deliveries.
pausedAtstring | nullrequired
When it was paused.
failingSincestring | nullrequired
Start of the current run of failed deliveries. Set while it keeps failing; cleared by any success. 3 days after this, it's paused automatically.
lastDeliveryAtstring | nullrequired
The last delivery attempt, successful or not.
lastSuccessAtstring | nullrequired
The last delivery your server accepted (answered 2xx).
recentFailuresintegerrequired
Deliveries from the last 24 hours whose latest attempt failed, including ones still being retried.
createdAtstringrequired
When it was added.

The signing secret is never returned by the API.

List webhooks#

GEThttps://api.waconnect.ai/v1/webhooks

Returns your webhooks, newest first. A key limited to some numbers only sees webhooks that receive events for at least one of its numbers.

curl https://api.waconnect.ai/v1/webhooks \
  -H "Authorization: Bearer wc_live_your_key"
200 OKjson
{ "data": ["…webhook objects…"] }

Get a webhook#

GEThttps://api.waconnect.ai/v1/webhooks/:id

Returns one webhook object. Answers 404 with WEBHOOK_NOT_FOUND when it isn't in your business, or your key can't see it.

Watch your webhook#

Messages of API numbers aren't stored in WaConnect, so events that fail for good are lost. Check your webhook every few minutes and alert your team when it's paused or failing.

watch-webhook.jsjs
const WEBHOOK_ID = "01a0f52b-7c1d-7e2f-9a3b-4c5d6e7f8a9b"
 
setInterval(async () => {
  const response = await fetch(`https://api.waconnect.ai/v1/webhooks/${WEBHOOK_ID}`, {
    headers: { Authorization: `Bearer ${process.env.WACONNECT_API_KEY}` },
  })
  const webhook = await response.json()
  if (webhook.status !== "active" || webhook.failingSince !== null) {
    await alertTeam(`The WaConnect webhook is ${webhook.status}: ${webhook.pausedReason ?? "deliveries are failing"}`)
  }
}, 5 * 60 * 1000)