Webhook Validation

Overview

To ensure webhook requests are authentic and have not been modified during transmission, EdfaPay can sign each webhook request using an HMAC-SHA256 signature.

When a Webhook Secret is configured, every webhook request includes a signature in the HTTP header. Your application should validate this signature before processing the webhook.

If no webhook secret is configured, no signature header will be sent.

Signature Header

Every signed webhook includes the following HTTP header:

X-EdfaPay-Signature: <signature>

The signature is generated using:

HMAC-SHA256(secret, raw_request_body)

Validation Steps

1. Read the webhook request body exactly as received.
2. Read the value of the X-EdfaPay-Signature header.
3. Generate your own HMAC-SHA256 signature using:
   • Your Webhook Secret
   • The raw request body
4. Compare your generated signature with the header value.
5. If both signatures match, process the webhook.
6. If they do not match, reject the request.

Example

Webhook Body

{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "orderId": "ORDER-12345",
  "amount": 100.00,
  "currencyCode": "682",
  "cardScheme": "Visa",
  "cardNumber": "4111 **** **** 1111",
  "cardChannel": "PHYSICAL_CARD",
  "status": "Success",
  "channel": "Payment Gateway",
  "type": "Purchase",
  "createdAt": "2026-08-03T12:00:00Z",
  "finishedAt": "2026-08-03T12:00:05Z",
  "merchantId": "11111111-2222-3333-4444-555555555555",
  "cardToken": "TKN-12345678-1234-1234-1234-123456789012",
  "pgDetails": {
    "reason": "Approved"
  },
  "rrn": "123456789012"
}

Webhook Secret

my-secret-key

Generate Signature

HMAC_SHA256(
    secret = "my-secret-key",
    message = raw_request_body
)

Compare the generated value with the value received in:

X-EdfaPay-Signature

If they match, the webhook is authentic.

Best Practices

• Always use the raw HTTP request body. Do not parse and serialize the JSON before calculating the signature.
• Keep your Webhook Secret confidential.
• Reject requests with an invalid signature by returning HTTP 401 Unauthorized or HTTP 403 Forbidden.
• Verify the signature before processing the webhook payload.

Signature Specification