Webhooks API

1. Enter your endpoint URL (must be https://).
2. Tick the events you want.
3. Save. A signing secret (whsec_...) is shown, you will use it to verify deliveries. You can read it again from the list at any time.

Your endpoint must be publicly reachable. The URL has to be https:// and resolve to a public internet address. Seaty refuses to deliver to localhost, private/internal addresses, or cloud-metadata hosts: such attempts are recorded as blocked in the delivery log and never sent. Test with a public tunnel (for example an ngrok https URL) rather than an internal hostname.

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "type": "balance.payment_recorded",
  "organisation_id": 24,
  "organisation_tag": "wmtc",
  "event_id": 1024,
  "event_tag": "spring-show",
  "created": "2026-06-04T12:00:00Z",
  "data": {
    "id": 90233,
    "guid": "f1c2...",
    "event_id": 1024,
    "payee_email": "buyer@example.com",
    "amount": 1500,
    "type_id": 1,
    "is_refund": false,
    "date_payment_made": "2026-06-04T00:00:00Z",
    "notes": "Cash on the door"
  }
}

import hashlib
import hmac

def is_valid(secret: str, signature_header: str, raw_body: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    expected = hmac.new(
        secret.encode(),
        f"{parts['t']}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

• Use a constant-time comparison (e.g. hmac.compare_digest, as above), never ==, so you do not leak the signature through timing.
• Reject stale timestamps to limit replay. Treat the delivery as invalid if t is more than 5 minutes from your own clock (abs(now - t) > 300). The t value is the unix timestamp in the X-Seaty-Signature header. Combined with deduplicating on the envelope id, this stops a captured payload from being replayed against you later.

• Return any 2xx quickly (within 10 seconds) to acknowledge receipt. Do the real work afterwards.
• Any non-2xx, a timeout, or a connection error is treated as a failure and retried with increasing backoff (about 1 min, 5 min, 30 min, then 2 hours, up to 5 attempts) before the delivery is marked failed. Redirects are not followed (a 3xx counts as a failure), so point the webhook at its final URL.
• Delivery is at least once: a retry can arrive after you already processed one. The envelope id is a unique id per event (not the resource id, which is in data) and stays the same across retries of that event, so deduplicate on id.
• Order is not guaranteed. Use created if you need to reason about sequence.

• After about 20 consecutive failed deliveries, or an endpoint that has been failing continuously for roughly 24 hours, the endpoint is automatically disabled and the organisation's administrators are emailed. No further events are sent to it until it is re-enabled.
• Fix the endpoint (make sure it is publicly reachable and returns a 2xx), then re-enable it from the dashboard. Re-enabling clears the failure count and resumes delivery. Events that fired while it was disabled are not back-filled.
• Separately, Seaty can suspend all webhooks for an organisation as a rare anti-abuse measure. While suspended, deliveries stop and creating or testing a webhook returns an error asking you to contact support@seaty.co.uk.

More event types (order updates, request approvals, and others) will be added to this catalogue as they come online. Subscribing only ever delivers the events that exist.