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