Svarly Webhooks

Event & Delivery Guide

Svarly receives and processes billing, telephony, and SMS webhook events from connected providers. This page describes event types, payload structures, verification, and retry expectations.

Event types Svarly receives

Stripe billing events

checkout.session.completedinvoice.payment_succeededinvoice.payment_failedcustomer.subscription.deleted

Endpoint: /api/stripe/webhook

Vonage call lifecycle events

startedringingansweredcompletedfailedtimeoutbusyunanswered

Endpoints: /api/vonage/answer, /api/vonage/event

Inbound SMS events

customer_confirmcustomer_cancelcustomer_modifystaff_estimate_reply

Endpoints: /api/sms/incoming, /api/vonage/sms-reply

Payload examples

Stripe: invoice.payment_failed

{
  "id": "evt_1Qx...",
  "type": "invoice.payment_failed",
  "created": 1772324890,
  "data": {
    "object": {
      "id": "in_1Qx...",
      "customer": "cus_R8...",
      "status": "open"
    }
  }
}

Vonage call event: completed

{
  "status": "completed",
  "conversation_uuid": "CON-8f3f...",
  "to": "+46769436246",
  "from": "+46701234567",
  "duration": 187,
  "timestamp": "2026-03-01T01:14:24.553Z"
}

Inbound SMS reply

{
  "msisdn": "+46701234567",
  "to": "+46769436246",
  "text": "JA"
}

Verification guide

Stripe signature validation

Svarly validates stripe-signature using the raw request body and STRIPE_WEBHOOK_SECRET. Invalid signatures return 400.

Vonage webhook validation

Vonage endpoints verify the authorization header via verifyVonageWebhook. Unauthorized requests return 401.

Internal tool webhook validation

Tool-style order endpoints (for example /api/vonage/order, /api/vonage/modify-order) use dedicated request verification and reject untrusted calls.

Retry policy & delivery semantics

Provider webhooks are expected to be retried by sender on non-2xx responses.
Svarly queues critical webhook processing into webhook_events for reliability and observability.
Failed webhook jobs are moved to failure/dead-letter tracking for manual replay flows.
Vonage call events prioritize call continuity: for most non-fallback paths, /api/vonage/event returns HTTP 200 with an empty body.
Stripe webhooks are idempotency-safe by event id and queue processing (duplicate deliveries should not create duplicate side effects).