Webhooks

​

Overview

​

Get started

​

Production checklist

1. Use HTTPS, not HTTP. Your endpoint URL must start with https://. We won’t deliver to plain http:// in production. Security →
2. Confirm each request actually came from us. Use the FD-Signature header to check authenticity. Skip this and anyone could forge events. How to verify →
3. Reply within 10 seconds. Send back 200 OK quickly, then do the heavy work in the background. Slow replies count as failures and we’ll retry. Delivery behavior →
4. Return 2xx for event types you don’t handle. A handler that throws on an unrecognized type turns our delivery into a failure. Acknowledge first, then decide what to process. Troubleshooting →
5. Don’t process the same event twice. We may deliver the same event more than once. Track which event.id values you’ve handled and skip duplicates. Idempotency →
6. Keep your signing secret safe. Treat it like a password: never commit it to git, store it in a secret manager, and rotate it from the dashboard if it ever leaks. Security →

​

Event types

​

Payload format

{
  "id": "04b97437-62cd-4ccb-b7eb-54765dbaa72d",
  "type": "earnings.created",
  "api_version": "2026-05-20",
  "livemode": true,
  "created": 1779309269,
  "data": {
    "object": { "...": "shape depends on type" }
  }
}

​

Headers

​

Verifying the signature

import hmac
import hashlib
import time

SIGNATURE_MAX_SKEW_SECONDS = 300  # 5 minutes

def verify(raw_body: bytes, header_value: str, secret: str) -> bool:
    try:
        parts = dict(piece.split("=", 1) for piece in header_value.split(","))
        ts = int(parts["t"])
        candidate = parts["v1"]
    except (KeyError, ValueError):
        return False

    # Reject anything outside the skew window — defeats replay attacks
    # if your signing secret ever leaks.
    if abs(int(time.time()) - ts) > SIGNATURE_MAX_SKEW_SECONDS:
        return False

    signing_input = f"{ts}.".encode("utf-8") + raw_body
    expected = hmac.new(
        secret.encode("utf-8"), signing_input, hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(candidate, expected)

import crypto from 'node:crypto'

const SIGNATURE_MAX_SKEW_SECONDS = 300 // 5 minutes

export function verify(rawBody, headerValue, secret) {
  let ts, candidate
  try {
    const parts = Object.fromEntries(
      headerValue.split(',').map((p) => p.split('=', 2)),
    )
    ts = parseInt(parts.t, 10)
    candidate = parts.v1
  } catch {
    return false
  }

  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > SIGNATURE_MAX_SKEW_SECONDS) {
    return false
  }

  const signingInput = Buffer.concat([
    Buffer.from(`${ts}.`, 'utf8'),
    Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8'),
  ])
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signingInput)
    .digest('hex')

  // Lengths must match before timingSafeEqual; otherwise it throws.
  const a = Buffer.from(candidate, 'hex')
  const b = Buffer.from(expected, 'hex')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

​

Delivery behavior

​

Idempotency

• Dedupe on id (e.g. insert into a processed_events table with a unique constraint and ignore conflicts).
• Don’t trust delivery order; events for the same resource can interleave.

​

Test mode

​

Security

• HTTPS only. We refuse to deliver to plain http:// URLs in production.
• SSRF defense. We resolve your URL’s IP at every delivery attempt and reject private (RFC 1918), loopback, link-local, and metadata-service ranges.
• Signing-secret rotation. Use Regenerate secret on the destination’s row whenever you suspect a leak. The old secret stops working as soon as you rotate, so deploy the new secret to your handler in lockstep.
• Secret access. Re-copy your secret from the destination’s row in the dashboard if you misplace it. Retrieval is gated by your dashboard login; API keys cannot read signing secrets.

​

Limits

​

Troubleshooting

1. You parsed the body before computing the HMAC. Always verify the raw bytes.
2. The signing secret in your config is stale after a rotation. Re-copy from the dashboard.
3. Your server has clock drift > 5 minutes. We reject signatures outside the skew window.

​

See also

• Webhook event types — the full catalog with payload schemas.
• How to set up webhooks — step-by-step walkthrough with a working Python receiver.
• Open the Webhooks dashboard to create your first destination.