Carbn includes a X-Webhook-Signature header with each webhook delivery for authenticity verification. This ensures that webhook events are genuinely from Carbn and haven’t been tampered with.

​
Signature Format

The header value is a base64 encoded RSA signature: <base64_encoded_signature>

​
Verification Process

  1. Extract the signature from the X-Webhook-Signature header
  2. Decode the signature using base64 decoding to get signature bytes
  3. Verify the signature using Carbn’s public key and the raw HTTP request body

​
Complete HTTP Request Example

POST /webhooks/carbn HTTP/1.1
Host: your-app.com
Content-Type: application/json
User-Agent: Java/17.0.14
X-Webhook-Event-Id: 1389bf11-20e2-44fe-8650-1e8ccfd9ba42
X-Webhook-Id: f79bc473-d45d-4026-86ec-864d4d047905
X-Webhook-Signature: lrmZCA323EV0oWMj9KZVcw5zEfeZzZSOmAKpcgzqPPF...

{"status": "PAYMENT_PROCESSED", "txn_id": "da4ac399-ed76-42f3-ba29-e4f4b7e2b46c", "user_id": "38758d6e-05f7-46a2-86d1-5ab45a49bc64"}

​
Security Best Practices

  1. Always verify webhook signatures using RSA public key verification
  2. Use HTTPS endpoints with valid certificates
  3. Implement idempotency using the X-Webhook-Event-Id header
  4. Return 200 status quickly to avoid timeouts
  5. Store public keys securely (use environment variables)
  6. Log webhook events for debugging and monitoring

​
Troubleshooting

​
Common Issues

  • Webhook not receiving events: Ensure webhook is enabled and endpoint returns 200 status
  • Signature verification fails: Use raw request body and correct RSA public key
  • Duplicate deliveries: Implement idempotency using X-Webhook-Event-Id header

​
Testing Your Webhook

You can test your webhook endpoint using the trigger webhook event endpoint: 
curl --request POST \
  --url https://api.carbnconnect.com/onboarding/api/v1/webhooks/trigger/{webhook_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <your-api-key>'

​
What’s Next?

Configure Webhooks

Learn how to set up and register webhooks
Proper webhook verification ensures the security and reliability of your integration with Carbn’s payment system.