Webhook Signature Headers

When webhook signing is enabled, TabaPay includes signature and delivery information in the webhook request headers.

A signature header is an HTTP header included with a webhook request that contains information the receiving system uses to verify the request came from the expected sender and wasn't altered.

Header	Description
`X-HMAC-Signature`	Contains the timestamp and HMAC signature used to verify the webhook delivery.
`Idempotency-Key`	Unique identifier for the webhook event. The value remains the same across retry attempts and can be used to identify duplicate deliveries.
`Content-Type`	Content type of the webhook payload. Value: `application/json`.

X-HMAC-Signature

The X-HMAC-Signature header contains a timestamp and HMAC-SHA256 digest generated using the webhook signing secret.

X-HMAC-Signature: t={timestamp},v1={signature}

During the 48-hour secret rotation period, the header includes signatures generated with both the current and previous signing secrets:

X-HMAC-Signature: t={timestamp},v1={currentSignature},v2={previousSignature}

Value	Description
`t`	Unix timestamp in seconds indicating when the webhook delivery was signed.
`v1`	HMAC-SHA256 digest generated using the current signing secret.
`v2`	HMAC-SHA256 digest generated using the previous signing secret. Returned only during the 48-hour secret rotation period.

During secret rotation, either v1 or v2 can be used to verify the webhook delivery.

Example

Content-Type: application/json
Idempotency-Key: example-idempotency-key
X-HMAC-Signature: t=1786000000,v1=77308cd2c7c660a1830f754fa41c8e8302e4897b093c44a4fcdd8685247719a6

For instructions on generating and rotating signing secrets, calculating signatures, verifying webhook deliveries, and handling verification failures, refer to Verifying Webhook Signatures.