Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Extract the request body as string.

  2. Extract timestamp from the Signature header.

  3. Concatenate timestamp and request body - use dot as separator: <timestamp>.<requestBody>.<timestamp>

  4. Use HMAC-SHA256 algorithm to compute the hexadecimal hash of string created in previous step. Use your hook secret as a HMAC key.

Then, verify that the computed signature is same as signature provided in Signature header (or same as any of signatures, if multiple secrets are valid).

Example

Here we provide example to demonstrate the signing process.

Example hook request body:

Code Block
{
    "eventId": "b2935024-5e46-4cf7-878f-5359526922e5",
    "eventType": "payment.statusChange",
    "eventTimestamp": "2024-05-07T15:27:32.197Z",
    "data": {
        "paymentId": "0dbe5c2f-3cf3-4177-84fb-5b25c7f6686f",
        "orderId": "c3ae08d7-5719-4112-bf67-bb9f03e74255",
        "status": "BOOKED"
    }
}

Example signature header (using secret value abcd):

Code Block
Signature: ts=2024-05-07T15:27:32.290Z;v0=a7745d8eb55151d67fa8e95197ce34a4276b7ced2f55982630e9275af57ad317

To verify the signature:

  1. Concatenate timestamp from signature header with request body as string

Code Block
2024-05-07T15:27:32.290Z.{"eventId":"b2935024-5e46-4cf7-878f-5359526922e5","eventType":"payment.statusChange","eventTimestamp":"2024-05-07T15:27:32.197Z","data":{"paymentId":"0dbe5c2f-3cf3-4177-84fb-5b25c7f6686f","orderId":"c3ae08d7-5719-4112-bf67-bb9f03e74255","status":"BOOKED"}}
  1. Use HMAC-SHA256 algorithm to compute the hexadecimal hash of string created in previous step.

Replay attacks prevention

...

  • Use HTTPS protocol for your hook endpoints

  • Store your hook secret securely

  • You can also roll hook secrets periodically

  • If your hook secret was compromised, regenerate the secret and use only the new secret to verify the signature

  • Do not accept webhook requests with invalid signature

  • Do not accept webhook requests with too old timestamp in Signature header

  • Optionally, you can also set up IP address whitelist and verify request originator IP address.

    • For production environment, our IP address is 35.189.196.34

    • For staging environment (used only in special cases upon agreement with client), our IP address is 34.79.17.248