Webhooks

A webhook endpoint is a URL Synex POSTs events to as they happen, so your integration reacts to changes instead of polling for them. The body of every delivery is exactly the event object GET /v1/events/{event} returns — same envelope, same snapshot — so you can build and test against the feed first and turn on delivery afterwards without changing your parser.

The webhook endpoint model

A team may hold 16 endpoints; the seventeenth create is 400 webhook_endpoint_limit_reached. Delete or disable one to make room.

URL requirements

Your endpoint URL is validated before it is stored, and again at delivery time. These are requirements, not preferences:

• https only. Plaintext delivery would put signed customer data on the wire in clear.
• A publicly routable host. A URL that points at — or whose hostname resolves into — a private, loopback, link-local, carrier-NAT or cloud metadata range is refused.
• No userinfo. https://user:password@host/path is rejected: credentials in a URL are sent on every delivery and logged by every proxy in between.
• At most 2048 characters.

Every rejection is 400 webhook_url_invalid with param naming url. The message names the problem class but never the address a hostname resolved to.

Because the check runs again at delivery time, an endpoint whose DNS is later re-pointed into a blocked range starts failing deliveries — and those failures consume attempts and count toward auto-disable exactly like any other.

Choosing enabled_events

Either a list of concrete types from the event catalog, or the single-element list ["*"]. "*" means every type including ones added in future, which is the right choice for a firehose consumer and the wrong one for a narrow integration that would rather opt in explicitly.

The two forms cannot be mixed. ["*", "passport.updated"] reads like a narrowing but is not one, so rather than silently subscribing you to everything it is rejected with 400 enabled_events_invalid — as is any type not in the catalog. Duplicates are collapsed silently.

Changing the subscription later is a PATCH, and it replaces the list rather than merging into it.

List webhook endpoints

curl https://api.synexcloud.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "we_8f3a2c1e9d7b4065",
      "object": "webhook_endpoint",
      "url": "https://hooks.kestrel-energy.example/synex",
      "enabled_events": ["passport.created", "passport.updated"],
      "status": "enabled",
      "description": "Production passport sync",
      "metadata": {},
      "last_success_at": "2026-07-28T09:12:44Z",
      "first_failed_at": null,
      "disabled_at": null,
      "created_at": "2026-07-14T11:03:19Z",
      "updated_at": "2026-07-28T09:12:44Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/webhook_endpoints"
}

Register an endpoint

curl https://api.synexcloud.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.kestrel-energy.example/synex",
    "enabled_events": ["passport.created", "passport.updated"],
    "description": "Production passport sync"
  }'

{
  "id": "we_8f3a2c1e9d7b4065",
  "object": "webhook_endpoint",
  "url": "https://hooks.kestrel-energy.example/synex",
  "secret": "whsec_5c1f8a3e7b0d296441fa7c8e2b5d0937e46a1c8f3b7d0e25",
  "enabled_events": ["passport.created", "passport.updated"],
  "status": "enabled",
  "description": "Production passport sync",
  "metadata": {},
  "last_success_at": null,
  "first_failed_at": null,
  "disabled_at": null,
  "created_at": "2026-07-28T09:12:44Z",
  "updated_at": "2026-07-28T09:12:44Z"
}

Retrieve an endpoint

curl https://api.synexcloud.com/v1/webhook_endpoints/we_8f3a2c1e9d7b4065 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "id": "we_8f3a2c1e9d7b4065",
  "object": "webhook_endpoint",
  "url": "https://hooks.kestrel-energy.example/synex",
  "enabled_events": ["passport.created", "passport.updated"],
  "status": "enabled",
  "description": "Production passport sync",
  "metadata": {},
  "last_success_at": "2026-07-28T09:12:44Z",
  "first_failed_at": null,
  "disabled_at": null,
  "created_at": "2026-07-14T11:03:19Z",
  "updated_at": "2026-07-28T09:12:44Z"
}

Update an endpoint

curl -X PATCH https://api.synexcloud.com/v1/webhook_endpoints/we_8f3a2c1e9d7b4065 \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "enabled"}'

{
  "id": "we_8f3a2c1e9d7b4065",
  "object": "webhook_endpoint",
  "url": "https://hooks.kestrel-energy.example/synex",
  "enabled_events": ["passport.created", "passport.updated"],
  "status": "enabled",
  "description": "Production passport sync",
  "metadata": {},
  "last_success_at": "2026-07-28T09:12:44Z",
  "first_failed_at": null,
  "disabled_at": null,
  "created_at": "2026-07-14T11:03:19Z",
  "updated_at": "2026-07-28T11:41:02Z"
}

Delete an endpoint

curl -X DELETE https://api.synexcloud.com/v1/webhook_endpoints/we_8f3a2c1e9d7b4065 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "webhook_endpoint",
  "id": "we_8f3a2c1e9d7b4065",
  "deleted": true
}

Roll the signing secret

curl -X POST https://api.synexcloud.com/v1/webhook_endpoints/we_8f3a2c1e9d7b4065/roll_secret \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "id": "we_8f3a2c1e9d7b4065",
  "object": "webhook_endpoint",
  "url": "https://hooks.kestrel-energy.example/synex",
  "secret": "whsec_1a7d0c4f9e2b6538d0af7c3e1b9d5024f8c6a3e70b14d29f",
  "enabled_events": ["passport.created", "passport.updated"],
  "status": "enabled",
  "description": "Production passport sync",
  "metadata": {},
  "last_success_at": "2026-07-28T09:12:44Z",
  "first_failed_at": null,
  "disabled_at": null,
  "created_at": "2026-07-14T11:03:19Z",
  "updated_at": "2026-07-28T12:00:00Z"
}

List deliveries

curl https://api.synexcloud.com/v1/webhook_endpoints/we_8f3a2c1e9d7b4065/deliveries \
  -H "Authorization: Bearer $SYNEX_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "wd_7a0c3e5b1d8f4926",
      "object": "webhook_delivery",
      "event": "evt_9b3e5d7c0a2f1846",
      "status": "failed",
      "attempt_count": 3,
      "last_http_status": 502,
      "last_error": "HTTP 502: <html><head><title>502 Bad Gateway</title>",
      "last_attempted_at": "2026-07-22T14:04:37Z",
      "next_retry_at": "2026-07-22T14:14:37Z",
      "delivered_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/webhook_endpoints/we_8f3a2c1e9d7b4065/deliveries"
}

The delivery contract

Synex sends a POST with a JSON body that is the event object, and these headers:

Rules of the exchange:

• Only a 2xx counts as success. Anything else is a failure and will be retried.
• Redirects are never followed. A 3xx is recorded as a failure. Following one would hand the destination to the HTTP client after the URL checks had already approved a different host, which is the whole bug class those checks exist to prevent. Register the final URL.
• Timeouts are 5 seconds to connect and 10 seconds in total. Acknowledge fast and do your work asynchronously — a slow consumer converts into a failed delivery. Return 2xx as soon as you have durably queued the event.

Verifying the signature

The signature is HMAC-SHA256 over the string "{t}.{raw_body}", keyed with your endpoint secret, where t is the unix timestamp from the header.

Two properties of that construction carry the whole design. The timestamp is inside the signed string, not merely alongside it, so it cannot be rewritten without invalidating the signature — which is what makes a freshness check meaningful. And the body is signed as the raw bytes on the wire, never a re-serialization: decode the JSON and re-encode it before verifying and key order, unicode escaping and float formatting will all differ, so every signature will appear invalid. Capture the raw body before your framework parses it.

function synex_verify(string $rawBody, string $header, string $secret): bool
{
    $timestamp = null;
    $signatures = [];

    foreach (explode(',', $header) as $part) {
        $pair = explode('=', trim($part), 2);

        if (count($pair) !== 2) {
            continue;
        }

        [$key, $value] = $pair;

        if ($key === 't' && preg_match('/^\d+$/', $value) === 1) {
            $timestamp = (int) $value;
        } elseif ($key === 'v1' && $value !== '') {
            // There may be TWO v1 entries during a secret roll.
            $signatures[] = $value;
        }
    }

    if ($timestamp === null || $signatures === []) {
        return false;
    }

    // Reject stale and future-dated deliveries alike: 5 minutes either way.
    if (abs(time() - $timestamp) > 300) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    $matched = false;

    foreach ($signatures as $candidate) {
        // hash_equals is constant-time. The loop deliberately does not break
        // early — returning on the first match leaks, through timing, which
        // of two signatures in a rolled header was the live one.
        $matched = hash_equals($expected, $candidate) || $matched;
    }

    return $matched;
}

In any language, the same five steps:

1. Read the raw request body as bytes, before any JSON parsing.
2. Parse the Synex-Signature header into t and a LIST of v1 values.
3. Reject if |now - t| > 300 seconds.
4. expected = HMAC_SHA256(key = secret, message = t + "." + rawBody), hex.
5. Return true if expected equals ANY v1 value, compared in CONSTANT TIME.

Four details are easy to get wrong and each one breaks verification silently:

• Scan every v1= entry. During a 24-hour roll overlap there are two. Code that reads the first and stops will reject half the deliveries it should accept — and only during a rotation, which is exactly when you are not looking.
• Compare in constant time. hash_equals, crypto.timingSafeEqual, hmac.compare_digest. A plain == on a signature leaks it a byte at a time.
• Tolerance is 300 seconds, checked in both directions. A signature from the future is as much a sign of a forged or misconfigured sender as one from last week.
• Sign the raw body, as above.

Unknown keys in the header are safe to ignore — the format is designed to grow, and the v1 tag is a version marker so a future scheme can be added alongside it rather than replacing it.

Retries and delivery semantics

A failed delivery is retried up to 8 attempts total, with jittered backoff at roughly:

That is about three days of trying. When the last attempt fails the delivery is marked exhausted and nothing further is sent for that event.

Delivery is at-least-once, with no ordering guarantee. Both halves matter:

• Deduplicate on event.id. The same event can legitimately arrive more than once — a retry after your server accepted the request but failed to answer in time, for instance. Record processed ids and discard repeats. Synex-Webhook-Id identifies the delivery and is stable across retries of the same one, which makes it a useful log correlator; event.id is the correct idempotency key for your business logic.
• Never assume sequence. Two events about the same passport can arrive out of order, because a retried delivery can land after a later event's first attempt. Do not reconstruct state by replaying events in arrival order. When order matters, treat the event as a notification that something changed and re-fetch the object for current truth — the snapshot in data.object is the state at emission, not necessarily the state now.

Two edge cases are worth knowing about. An attempt is charged only when the request was actually made, so infrastructure trouble on our side never counts against your endpoint's health. And if an event is pruned by the 30-day retention while deliveries to it are still backing off, that delivery closes as exhausted with an explanatory error, and your endpoint's health is left untouched.

Auto-disable, and getting back

An endpoint that fails continuously for five days — no successful delivery since first_failed_at — is automatically disabled. status becomes disabled, disabled_at is set, and a webhook_endpoint.disabled event is emitted. That event is delivered to your other healthy endpoints and never to the one being disabled, which would be pointless.

A disabled endpoint is skipped during fan-out entirely: it accrues no deliveries at all, and events that occur while it is disabled are not queued up for later.

Re-enable with a PATCH to status: enabled once you have fixed the cause. That resumes future deliveries; it does not resurrect deliveries that already exhausted their attempts — catch up on those through the events feed.

A checklist for a new consumer

1. Serve https, on a publicly resolvable host.
2. Capture the raw request body before parsing.
3. Verify the signature: every v1= entry, constant-time compare, 300-second tolerance.
4. Return 2xx as soon as the event is durably queued — within 10 seconds.
5. Deduplicate on event.id.
6. Do not depend on ordering; re-fetch the object when current truth matters.
7. Handle data.truncated by re-fetching.
8. Tolerate event types you do not recognise.
9. Monitor first_failed_at on your endpoints, or subscribe something to webhook_endpoint.disabled.

Errors

See errors for the shared envelope.