Getting started

Quick start

This guide takes you from zero to a delivered, signed webhook. Allow about ten minutes.

Installation

Install the command-line tool. It needs no runtime other than the binary itself.

# macOS and Linux
curl -fsSL https://example.com/install.sh | sh

# or with npm
npm install -g example-cli

Check that it works with example --version.

Your first request

Every event has a type and a data object. Send one with curl:

curl https://api.example.com/v1/events \
  -H "Authorization: Bearer $EXAMPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "order.paid", "data": {"order": "ord_481"}}'

The response

The API replies straight away with the queued event. Delivery happens in the background.

{
  "id": "evt_2Hk9",
  "type": "order.paid",
  "status": "queued",
  "attempts": 0
}

Authentication

Authenticate with a secret key in the Authorization header. Keys starting with test_ only touch test mode.

Verify signatures

Each delivery includes Example-Timestamp and Example-Signature headers. Recompute the signature and compare in constant time:

import hmac, hashlib

def is_valid(secret, body, timestamp, signature):
    message = f"{timestamp}.{body}".encode()
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Replay protection

Reject any request whose timestamp is more than five minutes old.

Errors and retries

Any response outside the 2xx range counts as a failure. Example API retries after 1 minute, 5 minutes, 30 minutes, and then every few hours, for up to 72 hours.

Rate limits

The API accepts 100 requests per second per key. Over the limit, it returns 429 with a Retry-After header.

Next steps

• Read the changelog for recent changes.
• See pricing when you are ready for live traffic.