Deliveries and retries

A delivery is one event headed to one endpoint. If three of your endpoints subscribe to contact.created, one new contact produces three deliveries, each tracked and retried on its own.

What counts as delivered

Ciarem sends the event the moment it happens, usually within a few seconds, and waits up to 10 seconds for your server to answer.

Your server	Result
Answers with any `2xx` status	Delivered. Ciarem does not read the response body.
Answers with `3xx`, `4xx`, or `5xx`	Failed. Redirects are not followed.
Takes longer than 10 seconds	Failed.
Refuses the connection, has an invalid TLS certificate, or cannot be resolved	Failed.

A failed delivery is retried automatically.

Retries

After a failure, Ciarem waits and tries again, with a longer wait each time:

Attempt	Wait after the previous failure
2nd	1 minute
3rd	5 minutes
4th	30 minutes
5th	2 hours
6th and later	8 hours each

Retries continue until the delivery is 3 days old. After that Ciarem gives up on it and marks it Failed. In practice that is about 14 attempts. Retries run once a minute, so an attempt can start up to a minute after its scheduled time. Every attempt sends the same body with the same event id. Only the Ciarem-Signature header changes, because each attempt is signed with a fresh timestamp.

Delivery statuses

In the dashboard	In the API	Meaning
Pending	`pending`	Queued, not attempted yet, or queued to be sent again.
Delivered	`succeeded`	Your server answered `2xx`.
Retrying	`failed`	The last attempt failed. Another one is scheduled at `next_attempt_at`.
Failed	`exhausted`	Ciarem stopped trying: the delivery passed 3 days, or its endpoint was disabled.

When an endpoint keeps failing

If every delivery to an endpoint fails for 3 days in a row, Ciarem turns the endpoint off. In the dashboard it shows Disabled after repeated failures; in the API, enabled is false and disabled_reason is auto_failures. A single successful delivery resets the count, so an endpoint with occasional failures is never disabled. While an endpoint is disabled:

Nothing is sent to it, and events that happen in the meantime are not saved for later.
Deliveries that were waiting for a retry are marked Failed.

To turn it back on, fix your server, then choose Enable in the endpoint’s menu, or send PATCH /v1/webhook-endpoints/{id} with {"enabled": true}. Delivery resumes with new events from that point on. To recover what you missed, see Catching up after downtime.

Pausing an endpoint yourself

Choose Disable in the endpoint’s menu, or send {"enabled": false}, to stop deliveries without deleting the endpoint. It behaves like the automatic case: nothing is sent while it is off, waiting retries are dropped, and enabling it later does not replay old events. disabled_reason is user. Deleting an endpoint also deletes its delivery log.

If your plan changes

Webhooks are part of API access. If your organization moves to a plan without it, or a trial ends without a subscription, Ciarem stops sending events immediately. Your endpoints are kept, and deliveries resume on their own when you are back on Growth or Scale. Events that happened in between are not sent afterwards.

Duplicates and order

Build your handler around two facts: The same event can arrive more than once. Ciarem guarantees each event is delivered at least once, not exactly once. A retry after your server processed the event but answered too slowly is the usual cause. Make handling safe to repeat:

Store the id of each event you process and skip any id you have seen before. Keeping ids for a few days is enough, since retries stop after 3 days.
Or make the action itself repeatable, for example “set the contact’s stage to X” instead of “move the contact one stage forward”.

Events can arrive out of order. A retried event arrives after newer ones, and two events seconds apart can swap places. Don’t assume the last event you received is the latest state:

Compare created_at on the envelope, or updated_at on the contact, with what you already stored, and ignore older data.
For conversations, expect that messages.inbound can arrive before the conversation.created of the same conversation.
When order matters, treat the event as a signal and read the current state from the API.

The delivery log

Every delivery of the last 30 days is recorded, with the exact body that was sent. In the dashboard: open Settings → Webhooks and click an endpoint. The Deliveries table shows each event, its status, your server’s response code, and the number of attempts. Click a row to see the body that was sent, the event id, your server’s response or the error, and the last and next attempts. With the API:

curl "https://api.ciarem.ai/v1/webhook-endpoints/whe_…/deliveries?status=failed&limit=50" \
  -H "Authorization: Bearer oak_YOUR_SECRET"

{
  "items": [
    {
      "id": "whd_…",
      "endpoint_id": "whe_…",
      "event_id": "evt_…",
      "event_type": "contact.updated",
      "status": "failed",
      "attempt_count": 3,
      "next_attempt_at": "2026-10-09T15:40:05.123456Z",
      "last_attempt_at": "2026-10-09T15:10:05.123456Z",
      "response_status": 500,
      "error": "endpoint answered 500",
      "created_at": "2026-10-09T15:04:05.123456Z",
      "payload": { "id": "evt_…", "type": "contact.updated", "…": "…" }
    }
  ],
  "next_cursor": null
}

Parameter
`status`	Optional. One of `pending`, `succeeded`, `failed`, `exhausted`.
`limit`	Optional. 1 to 100, default 20.
`cursor`	Optional. The `next_cursor` of the previous page. Results are newest first.

response_status is null when your server never answered (a timeout or a connection error); error then says what went wrong. Two things are not in the log: test events, and deliveries about a contact that has since been permanently erased, which are removed along with the contact’s data.

Sending a delivery again

You can resend any delivery in the log, whatever its status, for example after fixing a bug in your handler.

In the dashboard: click the delivery to open it, then click Send again.
With the API: POST /v1/webhook-deliveries/{delivery_id}/redeliver.

The delivery goes back to Pending and is sent within a minute, with the same body and the same event id. Because the id is unchanged, a handler that deduplicates will skip it: clear that id on your side first if you want it processed again. Sending again is refused with 409 endpoint_disabled while the endpoint is off. Enable it first.

Catching up after downtime

Retries cover outages of up to 3 days. For anything longer, or for the time an endpoint was disabled, reconcile from the API:

Contacts: list them with GET /v1/contacts and compare updated_at with what you hold.
Conversations: list them with GET /v1/conversations and read the messages of the ones that changed.

A periodic reconciliation like this is good practice even when everything works. It protects you from bugs on your side that webhooks alone cannot reveal.

Managing endpoints with the API

Everything in the dashboard is also available to an API key. Full request and response details are in the API reference, under Webhooks.

Request	Does
`GET /v1/webhook-endpoints`	Lists your endpoints.
`POST /v1/webhook-endpoints`	Creates an endpoint and returns its signing secret.
`GET /v1/webhook-endpoints/{id}`	Reads one endpoint.
`PATCH /v1/webhook-endpoints/{id}`	Changes `url`, `description`, `events`, or `enabled`. Send only the fields to change.
`DELETE /v1/webhook-endpoints/{id}`	Deletes the endpoint and its delivery log.
`POST /v1/webhook-endpoints/{id}/test`	Sends a test event now and returns your server’s answer.
`GET /v1/webhook-event-samples`	Returns the sample body of every event type.
`GET /v1/webhook-endpoints/{id}/deliveries`	Lists an endpoint’s deliveries.
`POST /v1/webhook-deliveries/{id}/redeliver`	Sends a delivery again.

Errors specific to webhooks, on top of the general ones:

Status	`detail`	Meaning
422	`{"code": "invalid_url", "message": "…"}`	The URL is not HTTPS, has no host, does not resolve, or points to a private address. `message` says which.
422	`"endpoint_limit_reached"`	The organization already has 10 endpoints. Delete one first.
422	field-level messages	For example an unknown event type, or `*` mixed with other types.
404	`"not_found"`	No endpoint or delivery with that id in your organization.
409	`"endpoint_disabled"`	You tried to send a delivery again while its endpoint is off.

These calls count toward your rate limit like any other API request. Events Ciarem sends to you do not.

Troubleshooting

Problem	What to check
No events arrive at all	Is the endpoint enabled? Is it subscribed to the event you expect? Send a test event: its result shows exactly what your server answered. Check that your plan includes webhooks.
The test works but real events don’t	The endpoint is probably not subscribed to that event type. Open it and review Events to send.
”This URL can’t be used”	The URL must be `https://` and resolve to a public address. Internal hostnames and `localhost` are refused. Use a tunnel for local development.
Deliveries fail with a `301` or `302`	Your server redirects, often from a URL without a trailing slash to one with it, or from a bare domain to `www`. Register the final URL.
Deliveries fail with `401` or `403`	Something in front of your server (a firewall, bot protection, or a login wall) blocks the request. Allow `POST` requests to that path. You can recognize Ciarem by the `Ciarem-Webhooks/1.0` user agent, but rely on the signature, not the user agent, for security.
Deliveries fail with a timeout	Your handler takes more than 10 seconds. Answer `200` first and do the work in the background.
Deliveries fail with a TLS or certificate error	Your certificate is expired, self-signed, or issued for a different hostname.
The signature doesn’t match	See When verification fails.
The same event arrives twice	Expected now and then. Deduplicate on the event `id`. If it happens for every event, check whether two endpoints point at the same URL.
`contact.updated` arrives several times for one edit	Each custom property that changes sends its own event, and stage and owner changes send theirs. See the event catalog.
An endpoint shows “Disabled after repeated failures”	It failed every delivery for 3 days. Fix the cause, then Enable it.
A delivery is missing from the log	The log keeps 30 days. Test events are never logged.

Getting started

Channels

Your AI agent

Using Ciarem

Integrations

Mobile app

Billing

API for developers

Deliveries and retries

What counts as delivered

Retries

Delivery statuses

When an endpoint keeps failing

Pausing an endpoint yourself

If your plan changes

Duplicates and order

The delivery log

Sending a delivery again

Catching up after downtime

Managing endpoints with the API

Troubleshooting

​What counts as delivered

​Retries

​Delivery statuses

​When an endpoint keeps failing

​Pausing an endpoint yourself

​If your plan changes

​Duplicates and order

​The delivery log

​Sending a delivery again

​Catching up after downtime

​Managing endpoints with the API

​Troubleshooting

What counts as delivered

Retries

Delivery statuses

When an endpoint keeps failing

Pausing an endpoint yourself

If your plan changes

Duplicates and order

The delivery log

Sending a delivery again

Catching up after downtime

Managing endpoints with the API

Troubleshooting