{% extends 'Layouts/Doc/default.html.twig' %} {% block title %}{{ 'app.documentation.menu.webhook.signatures'|trans }}{% endblock %} {% block headerPageTitle %}WEBHOOK {{ 'app.documentation.menu.webhook.signatures'|trans|upper }}{% endblock %} {% block body %}

Check the webhook signatures

Verify the events that Popina Order sends to your webhook endpoints.

Popina Order can optionally sign the webhook events it sends to your endpoints by including a signature in each event’s Popina Order-Signature header. This allows you to verify that the events were sent by Popina Order, not by a third party. You can verify signatures manually using your own solution.

Before you can verify signatures, you need to retrieve your endpoint’s secret from Popina Order support team.

Popina Order generates a unique secret key for each endpoint. If you use the same endpoint for both staging and production, note that the secret is different for each one. After this setup, Popina Order starts to sign each webhook it sends to the endpoint.

Preventing replay attacks

A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Popina Order includes a timestamp in the Popina-Order-Signature header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker can’t change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.

Popina Order generates the timestamp and signature each time we send an event to your endpoint. If Popina Order retries an event (for example, your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt.

Verifying signatures

The Popina-Order-Signature header included in each signed event contains a timestamp and one signature. The timestamp is prefixed by t=, and the signature is prefixed by s=.

Popina-Order-Signature:
t=1492774577,
s=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Note
Note that newlines have been added for clarity, but a real Popina-Order-Signature header is on a single line.

Popina Order generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and s corresponds to the signature. You can discard all other elements.

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating:

  • The timestamp (as a string)
  • The character .
  • The actual JSON payload (that is, the request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

{% endblock %} {% block stylesheets %} {% endblock %}