Skip to main content
Idempotent HTTP requests refer to the characteristic of certain HTTP methods that allows them to be safely and repeatedly executed without altering the state of the server beyond the initial request. These methods include GET, HEAD, PUT, and DELETE, while POST stands apart as a non-idempotent member. With convoy, you can now deduplicate events by specifying parts of the request for convoy to use as the idempotency key. While POST requests are not inherently idempotent, an idempotency key passed via a header can be used to de-duplicate them. When sending out webhook requests we set the X-Convoy-Idempotency-Key header whenever the event has an idempotency key, and your receiver can use it to de-duplicate events sent by Convoy. In the next two sections, we will talk about how to configure idempotency keys for both incoming and outgoing projects and how to de-duplicate events sent or received.

​
Idempotency in Incoming Projects

With Convoy, you can inspect parts of a request to extract the idempotency key. You can define idempotency keys in both the request body or header. When creating a source you can specify the location of the idempotency key which convoy will use to generate a SHA256 checksum value. To get started, create a source and specify the idempotency key locations in order. The locations can refer to request headers, body fields and query parameters. Convoy combines the values from all configured locations; they are not alternatives where the first available value wins. For request body key:
For request header key:
For request query param key:
Convoy concatenates the source name and the extracted values in the configured order, then generates a hexadecimal SHA256 checksum to check for duplicates within the project. Keep the source name and location order stable when handling redeliveries. For a single header location, the input is the source name followed by that header’s value. Duplicate events are recorded as duplicates and do not generate new deliveries. Receivers must still deduplicate delivery retries themselves; ingest deduplication does not guarantee that an endpoint processes a webhook only once.

​
Idempotency in Outgoing Projects

In outgoing projects you would need to specify an idempotency key in the request payload when creating the event. This works the same way when creating dynamic and fanout events. The idempotency key should be a unique value generated by the client. It is recommended to use the SHA256 of a UUID v4 string or any other sufficiently random string to ensure avoidance of collisions. We recommend a SHA256 string because the idempotency keys we generate for incoming projects are SHA256 strings.
As expected if you send the same idempotency key in a request it would create the event but no event delivery will be sent.

​
Outbound idempotency headers

The idempotency_key field above is the ingestion key Convoy uses to de-duplicate events coming into the project. Convoy sends that same value to the receiver in X-Convoy-Idempotency-Key by default. When an event has an idempotency key, its value takes precedence over any custom_headers entry with the same outbound header name. Set idempotency_key to the value your receiver should use:
Without an idempotency key, Convoy does not automatically add the default header. A value supplied in custom_headers can still be forwarded, but it does not enable ingest deduplication. Outgoing projects can change the outbound header name through config.request_id_header. With a custom name configured, idempotency_key is required when publishing events, and its value is written to that configured header.