Webhook Integration Guide

​

1. Webhook Subscription

​

💡 Example Requests

​

🔹 No Authentication

{
  "eventType": "DELIVERY_CHANNEL_STATUS_UPDATED",
  "callbackUrl": "https://partner.example.com/webhook"
}

​

🔹 API Key Authentication

{
  "eventType": "DELIVERY_CHANNEL_STATUS_UPDATED",
  "callbackUrl": "https://partner.example.com/webhook",
  "auth": {
    "type": "header",
    "headerName": "X-API-Key",
    "headerValue": "my-api-key"
  }
}

​

🔹 Basic Authentication

{
  "eventType": "DELIVERY_CHANNEL_STATUS_UPDATED",
  "callbackUrl": "https://partner.example.com/webhook",
  "auth": {
    "type": "basic",
    "username": "webhook-user",
    "password": "s3cr3t"
  }
}

​

🔹 HMAC Authentication

{
  "eventType": "DELIVERY_CHANNEL_STATUS_UPDATED",
  "callbackUrl": "https://partner.example.com/webhook",
  "auth": {
    "type": "hmac",
    "secret": "abcd1234"
  }
}

​

2. 🔐 Webhook Request Authentication

​

3. 🧮 Verifying HMAC Signatures

x-signature: sha256=3bdc5b07d7ef9b61b98ed5df4b1793e12fd...

• 🧾 The raw HTTP request body (exact bytes, not parsed JSON)
• 🔑 The shared secret you provided in your subscription

​

✅ Verification Steps

1. Extract the Signature
   Read the x-signature header from the incoming request.
2. Get the Raw Request Body
   Use the exact raw payload as received — do not reformat or parse.
3. Recompute the Signature
   Use HMAC-SHA256(secret, rawBody) to generate your own hash.
   Prefix it with "sha256=".
4. Compare Signatures
   Compare your computed signature with the received one.

​

4. 🔒 Security Best Practices

• 🚫 Never log or expose the shared secret.
• ✅ Always verify signatures for HMAC webhooks.
• 🔍 Reject any unsigned or invalid webhook requests.
• 🌐 Always use HTTPS for your webhook endpoint.
• 🧱 Keep your secret in secure configuration storage (not in code or client apps).

​

5. 🧪 Testing Webhooks

1. 🌍 Use a tool like ngrok or localtunnel to expose your local webhook endpoint publicly.
2. 🪵 Log incoming request headers and the raw body for debugging.
3. 🔑 Simulate signature generation manually using your shared secret to validate your implementation.
4. 🧩 Verify your signature verification logic before deploying to production.
5. 🔁 Test retry scenarios by sending multiple requests and validating idempotency.

💡 Tip: When testing, return different HTTP status codes (200, 401, 403) to confirm AccessRC handles each scenario as expected.

​

6. 📬 Response Expectations

• ✅ Return HTTP 2xx (usually 200 OK) when processing succeeds.
• 🔐 Return 401 Unauthorized if signature or authentication validation fails.
• ⏱️ Respond quickly (within a few seconds) — delayed responses may trigger retries.
• 🧾 Include a short, plain-text or JSON response body if helpful for debugging, but it’s optional.

​

💬 Example Responses

​

✅ Success

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Callback successfully received",
  "data": {}
}

​

❌ Invalid Signature (HMAC)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": "failed",
  "error": {
     "code": 401,
     "message": "Invalid Signature",
     "type": "Unauthorized"
  }
}

​

🚫 Invalid API KEY

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": "failed",
  "error": {
     "code": 401,
     "message": "Invalid API KEY",
     "type": "Unauthorized"
  }
}

​

🚫 Invalid Credentials

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": "failed",
  "error": {
     "code": 401,
     "message": "Invalid Credentials",
     "type": "Unauthorized"
  }
}