> ## Documentation Index
> Fetch the complete documentation index at: https://docs.carbn.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Verification

> Verify webhook authenticity using RSA signature verification

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

<CodeGroup>
  ```http HTTP Request theme={null}
  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"}
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.carbnconnect.com/onboarding/api/v1/webhooks/trigger/{webhook_id} \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: <api-key>'
  ```
</CodeGroup>

***

## What's Next?

<CardGroup cols={1}>
  <Card title="Configure Webhooks" icon="webhook" href="/documentation/getting-started/configure-webhook" arrow="true" horizontal>
    Learn how to set up and register webhooks
  </Card>
</CardGroup>

Proper webhook verification ensures the security and reliability of your integration with Carbn's payment system.