Journey Webhook Headers & Documentation

  • 25 October 2023
  • 3 replies

Hi team,

When testing Customer IO webhooks which are added to a Journey, I can see that there are two headers which are sent along with the payload:

  • x-cio-idempotency-key
  • x-cio-delivery-id

Unfortunately I can’t find any documentation on these. Can anyone enlighten me if these are stable, and how to use them?

The use case is that I am experiencing a race condition where my webhook response may take longer than the 4 second CIO timeout. This causes CIO to retry, and I need a stable way to determine if my service has already handled the request.


3 replies

Userlevel 3

Hi there,


The x-cio-idempotency-key header contains a unique hash, similar to the delivery_id, that is unique to each delivery. With this header, you can record the value of the header and then use it to de-duplicate/discard any additional sends that arrive with that same value.


I hope this clarifies!


Thanks @mau. How and when should x-cio-delivery-id be used, and what are the differences? In my testing, both remain unchanged when CustomerIO retries webhooks which have timed out

Userlevel 3

Hi @sebr


Since Delivery IDs are unique to each delivery, some people use the x-cio-delivery-id header to filter out duplicate webhooks that have the same Delivery ID. These duplicates can occur when a webhook is retried by our system when we don't get a timely response from their server.