> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/connect/webhook/best-practices.md).

# Best Practices

This guide presents recommendations to ensure robustness, reliability, and security when integrating with webhooks.

## Respond quickly

* Return a `202 Accepted` `HTTP` status code within 2 seconds of receiving a webhook request
* Use message queues (like RabbitMQ, SQS, or Kafka) to process events asynchronously
* Keep webhook endpoint processing light to avoid timeouts
* Consider implementing a separate worker process for complex event handling

## Validate the signature using the raw body bytes

* Always verify the webhook signature before processing any event
* Use the raw byte array of the request body without any transformation
* Avoid automatic parsing or character encoding conversions before validation
* Store your webhook secret securely (use environment variables or a secure vault)
* Example signature validation pseudo-code:

  ```
  calculatedSignature = HMAC-SHA256(webhookSecret, rawRequestBody)
  return calculatedSignature == receivedSignature
  ```

## Handle delays and retries

* Events may arrive late due to network issues or retry mechanisms
* Always check the event timestamp (`time` field) to determine event age
* Implement logic to handle old events appropriately for your use case
* Consider setting a maximum age threshold for processing events

## Implement idempotency

* The same event may be received multiple times due to network issues or retry attempts
* Use the event `id` field as an idempotency key to detect and ignore duplicates
* Store processed event IDs in a persistent database with appropriate TTL
* Make your event processing logic idempotent (safe to run multiple times)

## Monitor and track failures

* Implement comprehensive logging for all webhook events
* Monitor delivery metrics, response codes, and processing times
* Set up alerts for recurring failures or unusual patterns
* Keep a dedicated error queue for failed webhook processing attempts
* Implement a dashboard to visualize webhook health metrics

## Implement reconciliation routines

* If your application becomes unavailable, you may miss events
* Implement polling routines to fetch missed events during downtime periods
* Schedule regular consistency checks between your system and our API
* Consider implementing a dead letter queue for events that fail processing multiple times

## Configure network security

* Allow the following webhook service IPs in your firewall:
  * 34.234.120.59
  * 18.229.212.133
  * 3.218.90.124
  * 44.219.96.170
  * 18.235.54.162
* Ensure your SSL/TLS configuration is up-to-date
* Consider using a webhook proxy service for additional security
* Implement rate limiting on your webhook endpoints to prevent abuse

## Test your implementation

* Use our webhook testing tools to verify your integration
* Implement a development environment that can receive test webhooks
* Create automated tests to verify your webhook handling logic
* Regularly review and update your webhook integration


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-api/connect/webhook/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.