Webhooks

Test webhook events

Generate synthetic events to validate endpoint routing and signature handling without production traffic.

DevelopersAdvancedAvailable

What this guide covers

Send Test Mode events only to Test Mode endpoint configurations.
Exercise both successful and failing endpoint responses.
Confirm signatures, event IDs, and retry behavior before going live.

Use a Test Mode endpoint

Dashboard webhook tests target Test Mode endpoints only. Create or select an enabled Test Mode endpoint and subscribe it to yanola.webhook.test before sending a generic verification event.

Test Mode endpoints, like Live Mode endpoints, require a public HTTPS URL. For local development, point the endpoint at an HTTPS tunnel (cloudflared or ngrok) that forwards to your local receiver.

Send a generic verification event

Open the Agent Project's API → Webhooks page.
Switch to Test Mode.
Create or enable an endpoint that subscribes to Webhook test.
Choose Send test event for that endpoint.
Keep the generated idempotency key stable if the dashboard request itself must be retried.
Watch the returned delivery move from pending or delivering to succeeded, failed, or canceled.

Normalized generic test payload

json

{
  "id": "evt_...",
  "type": "yanola.webhook.test",
  "environment": "test",
  "createdAt": "2026-07-29T10:00:00.000Z",
  "data": {
    "synthetic": true,
    "purpose": "webhook_endpoint_verification",
    "endpointId": "...",
    "occurredAt": "2026-07-29T10:00:00.000Z"
  }
}

Test a retained Test Mode event

The dashboard test operation can also target a retained evt_ event from the same Agent Project and Test Mode environment. This exercises the selected endpoint using realistic normalized data without sending a WhatsApp message.

A missing, malformed, Live Mode, cross-project, or inaccessible event is not accepted as a Test Mode test source.

The production pipeline is preserved

A test delivery uses the endpoint's configured payload mode, the same exact signature contract, correlation headers, 10-second timeout, retry schedule, delivery records, response previews, and endpoint failure controls as production delivery.

The difference is isolation: the event and delivery stay in Test Mode and do not call Meta or consume message-send Yanola Balance.

Understand the dashboard result

Webhook test result fields
Field	Meaning
`event.id / event.type`	The evt_ identity and generic or selected Test Mode event type.
`event.generic`	True when Yanola created yanola.webhook.test for this verification.
`delivery.id / status`	The durable del_ record and its current lifecycle state.
`delivery.attemptCount`	How many endpoint attempts have started.
`delivery.nextAttemptAt`	Next scheduled retry, or null.
`idempotent`	The same dashboard test operation already created this durable delivery.
`dispatch`	enqueued, pending_dispatch, or already_terminal.

pending_dispatch is durable

If the queue is temporarily unavailable, the database delivery remains the source of truth and the recurring dispatcher can enqueue it later.

Failure diagnostics

Webhook test failures
Condition	What to check
`Invalid signature response`	The exact raw body reaches verification before JSON parsing and the Test secret matches this endpoint.
`404 endpoint or event`	The endpoint and optional event both belong to this Agent Project and Test Mode.
`422 endpoint disabled`	Enable the Test endpoint before sending.
`Timeout`	Persist and acknowledge within 10 seconds; move slow work to a queue.
`Repeated non-2xx`	Inspect the bounded response preview and fix the handler before the endpoint auto-disables.

Promote to Live Mode

Confirm the Test delivery succeeds and your durable store contains one event.
Confirm sending the same event again does not duplicate business side effects.
Exercise an intentional non-2xx response and observe a retry.
Create a separate Live Mode endpoint with a public HTTPS URL.
Store its separate copy-once Live signing secret.
Choose the same payload mode and only the production event and Sender filters you need.