Webhooks Explained: Signed Payloads and Retries
You've built an API and now need to notify other services when events happen. Polling is inefficient, so you implement webhooks. But soon you realize: how do you ensure the payload is authentic? What if the receiver is down? Without proper safeguards, webhooks can become a security hole and a reliability nightmare.
In this article, we'll walk through the essentials of webhooks, focusing on two critical aspects: signed payloads for security and retry mechanisms for reliability. We'll provide practical code examples and best practices to help you build robust webhook systems.
What Are Webhooks?
Webhooks are user-defined HTTP callbacks. They allow one system to send real-time data to another when a specific event occurs. Unlike APIs where you pull data, webhooks push data to you. This makes them ideal for event-driven architectures.
Common use cases include payment notifications (e.g., Stripe), CI/CD triggers (e.g., GitHub), and messaging platforms (e.g., Slack). The sender makes an HTTP POST request to a URL provided by the receiver, with a payload containing event details.
Why Secure Webhooks with Signed Payloads?
Webhook endpoints are publicly accessible, making them vulnerable to spoofing. An attacker could send fake payloads to trigger unintended actions. To prevent this, senders sign the payload using a shared secret. The receiver verifies the signature to ensure authenticity and integrity.
Signing typically involves generating an HMAC (Hash-based Message Authentication Code) of the payload using a secret key. The signature is sent in a header (e.g., X-Signature). The receiver recomputes the HMAC and compares it with the received signature.
How to Implement Signed Payloads
Let's see a simple example in Python using Flask. The sender computes the signature:
import hmac
import hashlib
import json
import requests
secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()
headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)
The receiver verifies the signature:
from flask import Flask, request, abort
import hmac
import hashlib
app = Flask(__name__)
secret = b'your_shared_secret'
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get('X-Signature')
body = request.get_data()
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
abort(401)
# Process payload
return '', 200
Best practices:
- Use a strong secret and rotate it periodically.
- Include a timestamp in the signed data to prevent replay attacks.
- Use
hmac.compare_digestfor constant-time comparison. - Sign the raw body, not the parsed JSON, to avoid inconsistencies.
Implementing Reliable Retries
Webhook delivery can fail due to network issues, receiver downtime, or processing errors. A robust system should retry failed deliveries with exponential backoff.
Retry Strategy
Common approach: retry up to N times with increasing delays (e.g., 1s, 5s, 30s, 5m, 30m). After exhausting retries, mark the delivery as failed and alert.
Here's a simple retry mechanism in Python using the requests library and tenacity:
from tenacity import retry, stop_after_attempt, wait_exponential
import requests
@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
headers = {'X-Signature': signature}
response = requests.post(url, json=payload, headers=headers, timeout=10)
response.raise_for_status()
return response
Best practices for retries:
- Use idempotency keys to allow receivers to deduplicate.
- Set a timeout for each request to avoid hanging.
- Log each attempt for debugging.
- Provide a way to manually retry from a dashboard.
Comparison: Signed Payloads vs. Basic Auth
| Approach | Security | Complexity | Replay Protection |
|---|---|---|---|
| Basic Auth | Low (credentials sent each time) | Low | No |
| Signed Payload (HMAC) | High | Medium | Yes (with timestamp) |
Step-by-Step: Building a Webhook Sender with Retries
- Define the event payload and include a unique event ID and timestamp.
- Compute the signature using HMAC-SHA256 over the raw body.
- Send the request with the signature in a header.
- Handle failures by retrying with exponential backoff.
- Log deliveries and provide visibility.
Testing Webhooks
Use tools like ngrok to expose your local server and test webhook delivery. Always verify signatures in your tests to catch issues early.
FAQ
What is a signed payload in webhooks?
A signed payload is a webhook request where the sender includes a cryptographic signature (usually HMAC) generated with a shared secret. The receiver verifies the signature to confirm the request is authentic and hasn't been tampered with.
How many times should I retry a failed webhook?
There's no fixed number, but common practice is 3 to 5 retries with exponential backoff. Consider your receiver's typical downtime and the criticality of the event. Always allow manual retries.
Can I use JWT for webhook signatures?
Yes, JWT can be used, but it's more complex. HMAC signatures are simpler and sufficient for most cases. If you need to include claims, JWT might be suitable.
Ready to test your webhook payloads? Use our JSON Formatter to validate and pretty-print your JSON payloads before sending.