Idempotency

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 aren’t normally non-idempotent, the introduction of 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 and this can be used 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, this is an ordered set of locations— valid parts of the request where the keys might be found. The locations include the request header, body and query params.

For request body key:

request.body.<field-in-body>

For request header key:

request.header.<header-name>

For request query param key:

request.query.<query-param-name>

Using the key(s) you provide convoy will generate a SHA256 checksum, and use it to check for duplicates, this same key will be sent to your endpoint which can also be used to de-duplicate events. Any duplicate event will be marked as a duplicate and be discarded.

​

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.

{
    "endpoint_id": "01H3PECSZYDEES152G7DDBW7MP",
    "data": {
        "name": "{{$randomAdjective}}",
        "email": "{{$randomEmail}}",
        "age": 10
    },
    "idempotency_key": "12d851d0255ea37d2a0253016e62d35047ab4a737b5bcd75fb8fddff4b029249",
    "custom_headers": {
        "header": "valve"
    },
    "event_type": "read"
}

As expected if you send the same idempotency key in a request it would create the event but no event delivery will be sent.