Securing a Webhook Handler

Since your handler endpoint is open to requests from the internet, it's important to examine incoming webhook events to ensure they're real. This guide provides some instructions to help you secure your implementation.

Timing attacks

A timing attack is where an attacker sends a specially-crafted message to your endpoint and measures the amount of time it takes for your systems to check the signature of the message. If you use a simple, insecure string comparison function (like your language's default String#equals function), the attacker can collect timing information and use it to gradually reveal the correct signing key.

To prevent timing attacks, always use a comparison function that operates in constant time when comparing signatures or hashes. This helps prevent an attacker from determining the secret signing key.

Replay attacks

A replay attack is where an attacker intercepts an authentic event payload and sends it to your system at a time of their choice in order to trigger a side effect.

To prevent replay attacks:

1. Ensure your server’s local time is synchronized with NTP.

2. Verify that the timestamp in the x-everee-webhook-timestamp header is within your tolerance threshold by comparing it to the current time. We recommend a threshold of 2 minutes or less.

3. Verify the signature of each webhook event, following the instructions in the Authenticating Webhook Events guide.

If the received timestamp is more than 2 minutes (or your preferred threshold) old, you should reject the webhook event by responding with something other than an HTTP status code 2xx. This will cause Everee to record a failure and schedule another delivery attempt after a delay.

Everee only sends webhook events to endpoints secured with HTTPS.