Receiving Deliveries

The request

Each delivery is an HTTPS POST with a JSON body.

The event reference shows a complete body for each event type. Events can gain new fields and values over time, so ignore fields you don’t recognize.

Verifying a delivery

Verify every delivery before acting on it:

1. The signed content is {webhook-id}.{webhook-timestamp}.{body}: the two header values and the raw body, joined by periods.
2. The key is the part of the secret after whsec_, Base64-decoded.
3. The expected signature is the HMAC-SHA256 of the signed content with that key, Base64-encoded.
4. The delivery is authentic when the expected signature equals the value after v1, in any of the header’s signatures.

Reject a webhook-timestamp more than five minutes from the current time, to stop old deliveries from being replayed.

The scheme follows the Standard Webhooks specification, so the Standard Webhooks libraries verify deliveries in many languages. The example below needs only the Python standard library (3.6 or later).

import base64
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 5 * 60
def signature_matches(secret: str, message_id: str, timestamp: str,
                      signature_header: str, body: bytes) -> bool:
    key = base64.b64decode(secret[len('whsec_'):])
    signed_content = f'{message_id}.{timestamp}.'.encode() + body
    expected = base64.b64encode(
        hmac.new(key, signed_content, hashlib.sha256).digest())
    for signature in signature_header.split(' '):
        version, _, value = signature.partition(',')
        if version == 'v1' and hmac.compare_digest(value.encode(), expected):
            return True
    return False
def verify_webhook(secret: str, headers: dict, body: bytes) -> bool:
    """headers: the request's headers, keyed by lower-case name.
    body: the raw request body, exactly as received."""
    timestamp = headers['webhook-timestamp']
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    return signature_matches(secret, headers['webhook-id'], timestamp,
                             headers['webhook-signature'], body)

Responses and retries

Each retry uses the subscription’s current URL and secret. Pausing or deleting a subscription cancels its pending retries.

Duplicates and ordering

Delivery is at least once. A repeated delivery carries the same webhook-id, so use it to skip deliveries you have already processed.

A new event for the same order or package has a new webhook-id: order.shipped again when a package gains a tracking number, and order.whready again when an order re-enters the warehouse system under a new order number.

Deliveries can arrive out of order. timestamp gives the time each event happened.