Webhooks

What webhooks are

Webhooks are automated HTTP POST requests sent to a URL you specify. Instead of polling the API for changes, your server receives a notification the moment an event occurs. Each webhook payload includes the event type, a timestamp, and the relevant data.

Creating an endpoint

Navigate to Admin, then Growth, then Webhooks. Click Create Endpoint. Enter a name for the endpoint (for your reference), the destination URL where payloads should be sent, and optionally filter which event types you want to receive. A signing secret is generated automatically — you will need this to verify incoming payloads.

Event types

The following event types are available. Each type corresponds to a specific action in the platform.

Event filtering

By default, a new endpoint receives all event types. Use the event filter to select only the types you care about. This reduces noise and processing on your server. You can update filters at any time without recreating the endpoint.

Signature verification

Every webhook request includes a signature header for security. Use the endpoint's signing secret to verify that the payload was sent by Kagibag and has not been tampered with.

// The signature is included in the request headers
// Verify using HMAC-SHA256 with your endpoint secret
const signature = request.headers['x-webhook-signature'];
const expected = hmac('sha256', endpointSecret, request.body);
const isValid = timingSafeEqual(signature, expected);

Delivery and retries

When a delivery fails (your server returns a non-2xx status code or times out), Kagibag retries automatically. Retries use exponential backoff — each attempt waits longer than the previous one. The system makes up to six attempts by default. After all attempts are exhausted, the delivery is marked as failed.

Monitoring deliveries

View delivery history for each endpoint in the Webhooks section. Each delivery shows the event type, HTTP status code, number of attempts, timestamps, and any error messages. Click into a delivery to inspect the full request payload — useful for debugging integration issues.

Testing

Use the Send Test button on any endpoint to fire a test payload. The test uses the order.paid event type with a test: true flag in the data. This lets you verify your endpoint is reachable and processing payloads correctly before going live.

Troubleshooting

Common issues and how to resolve them.