Webhooks overview

Configure an endpoint

Webhook endpoint lifecycle is managed from the Agent Project dashboard, not through public /v1 endpoint-creation routes. Open API → Webhooks, select Live Mode or Test Mode, and create the destination in that environment.

Yanola creates deliveries only for enabled endpoints whose event and optional Sender filters match the event. Disabled endpoints keep their configuration but receive no new deliveries.

Store the copy-once signing secret

Yanola shows the endpoint signing secret only when the endpoint is created or its secret is rotated. Store the whsec_ value in a server-side secret manager as YANOLA_WEBHOOK_SECRET.

Rotating a secret creates a bounded overlap in which Yanola signs with the active and retiring secrets. The yanola-signature header contains one v1 digest per accepted secret so you can deploy the new secret without dropping deliveries.

1. Create the endpoint and copy the secret before closing the dialog.
2. Store separate secrets for Live Mode and Test Mode endpoints.
3. Never expose the secret in browser code, source control, logs, or support screenshots.
4. When rotating, deploy the new secret promptly and remove the retired secret after the dashboard grace period ends.

Delivery request contract

Yanola sends an HTTP POST with an application/json body. The payload bytes are signed before delivery; verify them before JSON parsing or any side effect.

Stable webhook compatibility

The signed headers, three payload-mode identities, normalized Event envelope, any-2xx acknowledgement, and at-least-once delivery semantics are part of the GA contract. Yanola does not remove or reinterpret them within v1.

New optional normalized fields and newly supported event types are additive. A new event type reaches an endpoint only after it is included in that endpoint's subscription. Ignore unknown fields, handle raw as nullable in yanola_with_raw mode, and treat provider-compatible fields in meta mode as extensible.

Acknowledge durable acceptance

Yanola considers any 2xx response successful. Every other status, connection failure, or 10-second timeout is a failed attempt and can be retried.

1. Read the exact raw request body.
2. Verify yanola-signature and its timestamp before parsing JSON.
3. Validate the payload shape selected by yanola-payload-format.
4. Atomically deduplicate and persist the event using yanola-event-id or the normalized event id.
5. Return 2xx only after durable acceptance.
6. Process slow business work asynchronously after the response.

Environment and subscription isolation

Live events are dispatched only to matching Live endpoints and Test events only to matching Test endpoints. Use separate URLs or route configuration when you want an obvious operational boundary.

Webhook endpoint counts, payload retention, and throughput can be controlled by the Yanola Subscription. Inbound webhook processing and Test Mode delivery do not consume message-send Yanola Balance.

Inspect delivery state

Use the dashboard Delivery history or an API key with webhooks:read to inspect safe delivery summaries. Public delivery reads expose status, attempts, timing, response status, a bounded redacted response preview, payload format, and replay state—not endpoint URLs, secrets, request bodies, or unredacted responses.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const failures = await yanola.webhookDeliveries.list({
  status: "failed",
  createdAfter: "2026-07-29T00:00:00.000Z",
  limit: 100,
})

for (const delivery of failures.data) {
  console.log(
    delivery.id,
    delivery.eventId,
    delivery.attemptCount,
    delivery.responseStatus
  )
}

Production checklist

1. Use a public HTTPS endpoint and keep DNS targets public.
2. Store the copy-once signing secret in a server-side secret manager.
3. Verify signatures over raw bytes with the SDK helper.
4. Deduplicate event processing and retain safe correlation IDs.
5. Return 2xx within 10 seconds after durable acceptance.
6. Monitor failed deliveries and auto-disabled endpoints.
7. Exercise the same handler with a Test Mode endpoint before enabling Live Mode.