Webhooks Explained: Signed Payloads and Retries

Backend2026-11-14TryQuickToolBox

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:

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:

Comparison: Signed Payloads vs. Basic Auth

ApproachSecurityComplexityReplay Protection
Basic AuthLow (credentials sent each time)LowNo
Signed Payload (HMAC)HighMediumYes (with timestamp)

Step-by-Step: Building a Webhook Sender with Retries

  1. Define the event payload and include a unique event ID and timestamp.
  2. Compute the signature using HMAC-SHA256 over the raw body.
  3. Send the request with the signature in a header.
  4. Handle failures by retrying with exponential backoff.
  5. 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.