🇫🇷 Norme · Subscribe to a webhook

This operation creates and configures a new webhook, providing:

• The callback URL

• The metadata to filter on subsets of events

The webhook belongs to the owner of the token and cannot be seen from others:

• It returns an id and a signing key (256 or 512 bits) that should be kept

• The signing key allows to validate the signature of each received event.

How the signature is managed:

• At webhook creation a signing Key is randomly generated in a secure way

  • 256 bits are enough if the random generator is secure

  • 512 bits are necessary if the generator is not secure

• Each time an event is sent:

  • a SHA-256 fingerprint is generated based on the concatenation of:

    • the JSON payload of the response (as is, no canonical format)

    • a separator : @

    • the current epoch time in seconds

  • a HMAC signature is computed over the fingerprint with the callback signing key

  • the signature is base64 encoded for the transport

The signature and the timestamp are returned in the following headers of the callback:

• Afnor-Signature is the signature (base64)

• Afnor-Signature-Timestamp is the epoch timestamp in seconds