Webhooks best practices

Bevy provides the webhook feature, but it requires some development and considerations on the external side not managed by Bevy

Here are some general best practices to help you handle inbound webhook traffic and make it more reliable:

1. Use a Dedicated Endpoint: It is advisable to establish a distinct endpoint for the URL of Bevy webhook to ensure that the incoming data does not interfere with any other processes.

2. Authentication and Security:

   • Verify Secret: Bevy webhook includes a secret that is sent in the headers of the incoming request. Use this header to verify that the request is coming from a trusted source.
     
   • Use HTTPS: Ensure that your webhook endpoint uses HTTPS to encrypt data in transit. This is enforced by Bevy and only HTTPS URLs are allowed.

3. Retry Mechanism:

   • Bevy will keep retrying sending the payload for the next 48 hours if you don't send back an HTTP 200 OK response.
   • During this time, the latest update to the data will be added to the data that the webhook is getting.
   • If the bulk option is enabled, all the latest updates for the pending records will be used. The number of the bulk has a maximum of 500 elements at a time, after which a new POST will be sent with the rest of the pending record.
   • If the bulk option is not enabled (the default), you'll receive one record per POST.

4. Acknowledge Receipt:

   • Acknowledge receipt of the webhook as soon as possible, typically with an HTTP 200 OK response. This lets the webhook provider know that you successfully received the data.
   • Note that Bevy will consider any response with a status code greater than or equal to 400 as an acknowledgment, but a 200 OK response is preferred.
   • If you can't process the webhook immediately, queue it for later processing and acknowledge the receipt to avoid duplicate deliveries.
   • Bevy will wait 60 seconds for a response from the external server, failing otherwise.

5. Logging and Monitoring:

   • Implement extensive logging to track incoming webhook requests and your system's responses.
   • Set up monitoring and alerting to detect and respond to any issues with webhook processing.

6. Rate Limiting and Throttling:

   • Implement rate limiting and throttling to prevent abuse and protect your system from excessive webhook requests.
   • A good way to avoid blocking inbound endpoints on your server is to queue the inbound payload for later processing.

7. Error Handling:

   • Define how your application handles errors. Notify appropriate parties if webhook processing fails repeatedly.

8. Data Validation:

   • Validate the incoming data to ensure it conforms to your expected format and contains all required fields.

By following these best practices, you can create a robust and reliable system for consuming inbound webhook traffic from Bevy while maintaining the security and integrity of your application. Remember that the specific implementation details may vary depending on your technology stack and the requirements of your webhook integrations.