Webhook Signature

To ensure that the requests you're getting at your webhook endpoint are coming from Poetic, we populate a X-Poetic-HMAC-SHA25 header with a HmacSHA256 hash which is generated by signing the request body with secret key which is shared between us.

A webhook signature is a security measure which allows you to verify the integrity and authenticity of the data you’re receiving. Each webhook contains a hash-based message authentication code (HMAC) in its header.

What is a HMAC?

A hash-based message authentication code (HMAC) is a type of message authentication code involving a cryptographic hash function and a secret cryptographic key. If any change is made to the data being sent, the resulting HMAC will be completely different from the original. Additionally, since the key is known only to the sender and the receiver, no valid HMAC can be regenerated by anyone else.

How to validate payloads by using a secret key?

Using signatures is simple. All you need to do is take the webhook's body and apply the HmacSHA256 hash function to it, using the secret key as the hash key. You then compare the resulting HMAC to the one contained in the header X-Poetic-HMAC-SHA25. If the HMACs are identical, then the data corresponds to what Poetic sent. (i.e.) this request came from Poetic. If they are different, this indicates that the data has been intercepted and altered in some way (i.e.) this request may have been tampered with in-transit or someone may be spoofing webhook notifications to your endpoint.