Skip to main content
Webhooks let Swytcho push event notifications directly to your server the moment something happens — a request completes, a request fails, or your usage crosses a threshold. Instead of polling the API repeatedly, your application receives a POST request with a structured payload and can react immediately.

Supported Event Types

Register a Webhook Endpoint

1

Open Webhook Settings

In the Swytcho dashboard, navigate to Settings → Webhooks.
2

Add an Endpoint

Click Add Endpoint, enter the HTTPS URL your server will listen on, and select the event types you want to receive.
3

Save and Copy the Secret

Click Save. Swytcho generates a signing secret for the endpoint — copy it now and store it securely. You’ll use it to verify incoming webhook signatures.

Webhook Payload

Swytcho sends an HTTP POST to your endpoint with a JSON body and a Swytcho-Signature header. The payload structure looks like this:
JSON
The top-level type field always matches one of the supported event types above.

Verify Webhook Signatures

Always verify the Swytcho-Signature header before processing a webhook payload. Skipping verification means your endpoint will accept forged requests from anyone who knows its URL.
Swytcho signs every webhook delivery using HMAC-SHA256 with your endpoint’s signing secret. The Swytcho-Signature header contains a timestamp and one or more signatures in the format t=<timestamp>,v1=<signature>.

Respond to Webhooks

Return an HTTP 200 status code as quickly as possible — ideally within 5 seconds. Swytcho considers any non-2xx response (or a timeout) a failed delivery and schedules a retry. If you need to do heavy processing, acknowledge the webhook immediately and handle the work asynchronously in a background job or queue.

Retry Behavior

If your endpoint fails to return a 2xx response, Swytcho automatically retries the delivery up to 5 times using exponential backoff: After 5 failed attempts, the delivery is marked as permanently failed and no further retries are made. You can view failed deliveries and manually retry them from Settings → Webhooks in the dashboard.
Use a tool like webhook.site or Svix Play to inspect and debug incoming webhook payloads during local development — no tunneling setup required.