Webhook security

When integrating with SuperAPI, it's important to ensure the origin of webhooks that are being sent into your system. To facilitate this we provide a message authentication code based on HMAC (https://en.wikipedia.org/wiki/HMAC)

Using this authentication code in practice looks like:

1. You receive a webhook from SuperAPI.
2. You extract the header x-superapi-signature from the request.
3. You sign the contents of our payload with the stored token and compare that with the extracted value from the header. If they match then you can attest the origin of the webhook was from SuperAPI.

We use SHA256 to sign the contents of the webhook.

It's worth noting as well that we sign webhooks at the time of delivery. For example, if we had a transient outage in the delivery of webhooks, e.g. your website is down, then a signing token rotation is performed, the delayed webhooks will be delivered with the new token used to sign them.

The webhook_signing_token value

A key component of this system is the token which is used to sign the request that is sent from us. This token is present on our product object in the form of the field webhook_signing_token. This key will be generated by us automatically and returned to you when a product is created. This key can also be updated via the API if required, this allows you to then periodically rotate the key.

Managing the webhook_signing_token

Normally you would store the webhook_signing_token within the database of your system and keep the value in sync with SuperAPI when rotating the key. To automate this process at the expense of an additional network request you could also:

1. Receive the webhook from SuperAPI.
2. Fetch the partner object from our API, this will contain the value of the signing token that was sent.
3. Perform the signing check against the body.

This removes the need to store the signing token in your system.