Retry Logic & Failure Handling

Catalogian automatically retries failed webhook deliveries with exponential backoff. This page covers the retry schedule, what counts as a failure, and how to monitor deliveries.

Retry schedule

A delivery job is attempted up to 5 times with exponential backoff: the first retry follows within seconds and every later retry waits longer than the one before it. Each attempt, successful or not, is recorded as a delivery record.

Attempt	Timing	Notes
1	Immediately when a change is detected	First delivery attempt
2	Seconds after attempt 1	First retry (backoff starts at ~5 seconds)
3 to 5	Each waits longer than the previous	Exponential backoff
After attempt 5		Marked as failed; the webhook keeps receiving future events

What counts as a failure

A delivery is considered failed if:

• Your endpoint returns a non-2xx HTTP status code (e.g. 400, 500)
• Your endpoint doesn't respond within 10 seconds
• The connection is refused or the DNS lookup fails
• The TLS handshake fails (e.g. expired certificate)

Respond quickly. Return a 2xx status immediately and process the webhook payload asynchronously. If your handler takes longer than 10 seconds, Catalogian treats it as a timeout and retries — potentially causing duplicate processing.

Handling duplicates

Due to retries, your endpoint may receive the same webhook more than once. Use the X-Catalogian-Delivery header to deduplicate:

app.post("/webhooks/catalogian", async (req, res) => {
  const deliveryId = req.headers["x-catalogian-delivery"];

  // Check if already processed
  if (await isProcessed(deliveryId)) {
    return res.status(200).send("Already processed");
  }

  // Mark as processing before doing work
  await markProcessing(deliveryId);

  // Process the payload...
  res.status(200).send("OK");
});

Monitoring deliveries

View delivery status and history in the dashboard under Source → Webhooks → Deliveries, or query the API:

GET /v1/sources/:id/webhooks/:webhookId/deliveries
Authorization: Bearer cat_live_...

Each delivery record includes:

Field	Description
`id`	Unique delivery ID
`deltaEventId`	The delta event this delivery carries
`status`	`success` or `failed`
`attempt`	Which attempt this record is (1 to 5)
`statusCode`	The HTTP status code your endpoint returned, when it answered
`error`	Error message if delivery failed
`deliveredAt`	When this attempt was made

Automatic disabling

Catalogian does not automatically disable webhooks after consecutive failures. Your webhook will continue to receive deliveries on future delta events even if previous deliveries failed. You can manually disable a webhook in the dashboard or via the API:

PATCH /v1/sources/:id/webhooks/:webhookId
Authorization: Bearer cat_live_...
Content-Type: application/json

{ "enabled": false }

Best practices

•Respond within 1 second. Queue the payload for background processing and return 200 immediately.
•Deduplicate on delivery ID. Store processed delivery IDs to handle retries gracefully.
•Use HTTPS. Webhook URLs must use HTTPS in production for security.
•Verify signatures. Always verify the HMAC signature before processing.
•Monitor the delivery log. Check the dashboard periodically for failed deliveries — they may indicate issues with your endpoint.

See the complete webhook payload schema. Payload Reference →