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

Last updated