Idempotency, retries, and webhook delivery: building resilient Slab5 integrations

Every webhook is going to fail at some point. Every API call is going to retry. Every agent is going to issue the same write twice. Resilient integrations assume all of that on day one.

The primitives Slab5 ships with for handling it: idempotency keys, automatic webhook retries with backoff, audit log replay.

Idempotency on every write

Every write endpoint accepts an idempotency_key. Use it.

``http POST /v1/leads Idempotency-Key: lead-from-form-2026-05-10-abc123 ``

If the request retries (your network blipped, your process restarted), Slab5 returns the original result rather than creating a second record. The key is stable per *logical operation*, not per HTTP request. A good pattern: hash the inputs that should make two requests equivalent.

MCP tools accept the same key as a parameter. Same rules.

Webhook delivery is retried for you

If your endpoint returns non-2xx or times out, Slab5 retries with exponential backoff. You can inspect deliveries and retry state through list_webhook_deliveries or in the dashboard.

What *your* handler must do:

• Be idempotent. Slab5 may deliver the same event twice. Use the event ID as a deduplication key on your side.
• Return 2xx fast. Do the work asynchronously if it takes more than a couple of seconds.
• Verify the webhook signature header against your endpoint secret before trusting the payload.

The dead-letter pattern

After retries exhaust, the delivery sits in a failed state. Build a small admin view that lists failed deliveries and lets a human replay them with one click. send_test_webhook_event is also useful for confirming a fix without waiting for real traffic.

Audit log replay

The nuclear option when your downstream system has drifted: read the audit log for a time range, replay the relevant create/update events into your system, reconcile.

This works because Slab5 records the event the moment it happens, regardless of whether your webhook handler succeeded. The audit log is the source of truth. Webhook delivery is an optimization layer on top of it.

What this looks like in production

A well-built Slab5 integration has four things:

1. Every write call uses an idempotency_key. 2. Every webhook handler dedups on event ID, verifies signature, and returns 2xx fast. 3. A small operator dashboard for failed deliveries. 4. A nightly reconciliation job that reads the audit log and catches anything the webhooks missed.

Do those four things and your integration survives outages, deploys, and 3 AM incidents without manual intervention. Skip them and you will discover, the hard way, which one you needed first.

Agents should always pass idempotency_key on every write call. The MCP runtime accepts it the same way REST does.

Every POST and PATCH accepts Idempotency-Key. Webhook deliveries auto-retry with backoff; inspect with list_webhook_deliveries. Audit log is queryable for replay.