---
url: /software_partners/build/webhooks/security.md
---
# 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.

The signature is what proves a webhook came from us. If you also want to restrict inbound traffic at the network layer, the addresses we deliver from are published under [Connectivity](/security/connectivity/index.html), along with our retry and timeout behaviour.

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, and 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](https://api.superapi.com.au/swaggerui#/product/SuperApiWeb.Api.V1.ProductController.show) 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 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 `product` object from our API with `GET /api/v1/product`; its `webhook_signing_token` is the token the webhook was signed with.
3. Perform the signing check against the body.

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