Webhook Security

Encryption

All provided subscriber endpoints must support HTTPS, as such TLS will be used to provide end-to-end encryption of webhook data.

Verification

All webhook HTTP requests will have a cryptographic signature attached as a header, which makes it possible to verify both the integrity and the authenticity of the data. This signing occurs using a secret signing key provided to you when the webhook endpoint was first registered.

Verifying a webhook signature

1. Extract the message signature from the signature request headers
2. Calculate the expected signature based on the received payload Compute an HMAC of the request body, using a SHA-256 hash function and the secret signing key provided to you during webhook registration
3. Compare the received message signature with the expected message signature.
   • If they match exactly, then the message is intact and originated in PlayHQ
   • If they do not match exactly, then the message should be rejected as it may be malformed or illegitimate

Calculating the signature is susceptible to any changes in the formatting of the request body. It should be performed against the raw request body as it has been transmitted (prior to any formatting such as addition of whitespace, new lines, etc.)