Set up webhooks

Webhooks push events to your system as they happen, so you don’t have to poll the API.

Add an endpoint

1. Go to Settings → Webhooks and click Add endpoint.
2. Enter your endpoint URL, e.g. https://your-server.com/vatli-events. It must be https:// and publicly reachable.
3. Optionally describe What it is for, e.g. n8n lead router.
4. Tick the Events to send. See Webhook events and payloads.
5. Save. Vatli shows the signing secret (whsec_…) once — copy it and click I have saved it.

Test it

Click Send test event. Vatli sends a signed webhook.test event through the real delivery path and shows whether your endpoint answered with a 2xx. It works even on a switched-off endpoint.

Delivery rules

• Reply with any 2xx within 10 seconds. Anything else — another status, a timeout, a refused connection or a redirect (redirects aren’t followed) — is a failure.
• Failed deliveries retry after 10s, 1m, 5m, 30m, 2h, 6h and 12h — one try plus 7 retries over about 21 hours.
• If every retry fails, the endpoint is marked unhealthy and your owners and admins get an email.
• After 24 hours without a single success, the endpoint is switched off and they’re emailed again. Switch it back on in Settings once it’s fixed — that resets its health.
• Reply first, work later. Do slow processing after returning your 2xx, or the timeout counts a success as a failure.

Delivery log

Settings → Webhooks keeps every attempt for 7 days: time, event, status code, the first 2 KB of your response, the error and the attempt number. From the log you can:

• Resend an event — it keeps the same event ID, so a receiver that already handled it can skip it.
• Rotate secret — the old secret stops working immediately.

Manage endpoints by API

With scope webhooks:manage:

• POST /api/v1/webhooks — { "url": "https://…", "events": ["message.received"], "description": "optional" }. The response includes the secret once.
• GET /api/v1/webhooks — list, with each endpoint’s health: healthy, unhealthy or disabled.
• GET, PATCH (url, description, events, is_active), DELETE /api/v1/webhooks/{id}.

Next: Verify webhook signatures.