Webhooks

A URL of yours that we POST a small JSON message to the moment something changes — so your code never asks on a timer.

• A webhook is a subscription: one URL plus the events you want there. Add a record to products, we POST to https://example.com/hooks/searchstack.
• Every active subscription for that event type gets its own signed message. What you didn’t tick is never sent.
• Your app reacts at once — clear a cache, start a release, post to Slack.

Auto-plays · use Back / Next to step through at your own pace.

Create a webhook

1. Developers → Webhooks → Create Webhook.
2. The URL: an HTTPS address on your side, reachable from the internet — up to 2,048 characters, never a private or loopback address.
3. The events, from the grouped list.
4. Create. The signing secret is shown; View secret shows it again later, Rotate secret issues a new one.

The events you can subscribe to

webhook.ping is not in the list: only Send test sends it.

What a delivery looks like

The body is the event’s data as JSON, sent as application/json. For a record event it is the record:

{
  "id": "tt1375666",
  "account_name": "acme",
  "list_name": "movies",
  "name": "Inception",
  "active": true
}

Verify the signature

Your URL is public, so anyone could POST to it. The signature is HMAC-SHA256 of timestamp + "." + body using your subscription’s secret, hex-encoded, prefixed sha256=.

• Recompute it and compare in constant time, as below.
• Reject a timestamp more than a few minutes off your clock, so old messages cannot be re-sent.
• X-Searchability-Event is not covered by the signature. Store each X-Searchability-Delivery id and refuse repeats, so a captured delivery cannot be re-sent under another event type; and check the body has the fields the event you act on carries.

public static bool IsValid(string secretBase64, string timestamp, string payload, string signatureHeader)
{
    const string Prefix = "sha256=";
    if (!signatureHeader.StartsWith(Prefix, StringComparison.Ordinal)) return false;

    var key = Convert.FromBase64String(secretBase64);
    var data = Encoding.UTF8.GetBytes(timestamp + "." + payload);

    using var hmac = new HMACSHA256(key);
    var expected = Convert.ToHexString(hmac.ComputeHash(data)).ToLowerInvariant();
    var actual = signatureHeader[Prefix.Length..];

    return CryptographicOperations.FixedTimeEquals(
        Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(actual));
}

const crypto = require('node:crypto');

function isValid(secretBase64, timestamp, payload, signatureHeader) {
  const prefix = 'sha256=';
  if (!signatureHeader.startsWith(prefix)) return false;

  const key = Buffer.from(secretBase64, 'base64');
  const expected = crypto.createHmac('sha256', key)
    .update(`${timestamp}.${payload}`).digest('hex');

  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(signatureHeader.slice(prefix.length), 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retries and failures

• Sent in the background. Each attempt allows 5 seconds to connect and 10 seconds for a reply: respond with a 2xx first, then do the slow work.
• Retried only on a temporary failure: 5xx, 408, 429, timeout, network error, or a DNS lookup that timed out or failed (SERVFAIL). A host that doesn’t exist fails at once. One quick retry, then re-sent after 1 min, 5 min, 30 min, 2 h and 6 h — 6 attempts over about 8.5 hours, then dropped.
• Any other 4xx is a failed delivery straight away. Redirects are not followed — a 3xx is a failed delivery too.
• A blocked address — the URL now resolves to a private, loopback or internal address, or DNS says its host doesn’t exist (no such name, or no address) — fails straight away too: no retry, logged as No response, and it counts toward suspension.
• A dead endpoint backs off. After 3 attempts in a row with no response or a 5xx, its deliveries pause for 1 minute, doubling to 30. A retry due in a pause is skipped with no log row; an event's first and last attempts wait for the pause and are always sent.
• 5 events in a row each failed suspend the webhook and email the account owner. Resume it once the URL works; events while suspended are not queued and not resent.
• At most 2 deliveries at once per webhook, and 4 per receiving host per account (per worker). Over that, a delivery waits 15 s, doubling to 4 min plus jitter, up to 20 times — 1 to 2 hours — then is sent anyway.
• No ordering guarantee. Retries, waits and parallel workers mean events can arrive out of order; read the current state when order matters.
• Expect duplicates. Keep the X-Searchability-Delivery ids you have seen and ignore repeats.
• Send test sends a webhook.ping any time, even while suspended — checks URL, signature and 2xx in one go. It never counts toward suspension.
• Delivery log (the webhook's View): one row per attempt sent, so a retried delivery shows several rows with the same delivery id. No response (status 0 in the API) means the URL never answered: timeout, refused or unreachable.
• The log keeps the first 32,000 characters of each body. The delivery itself sent the full body.

Limits

Manage subscriptions from the API

Everything but the secret is also on the public API and the MCP tools. Shapes in the API reference.

• No list route. Subscriptions and their ids are in GET /account/{account} (account_get) → webhook_subscriptions.
• A newly ticked event can take up to 30 s to start; an unticked one stops at once, queued retries included. A single-record write may still be routed by a server that hasn’t seen the change yet.
• Clients: client.Webhooks.… covers all but resume and the delivery log, which are API/MCP only for now.
• Rotating or viewing the secret is console-only, so a leaked API key can never read your signing secret.
• Refusals carry a code in the problem body:

• Code 5 is never returned.
• A create or edit whose DNS lookup timed out, or a create that couldn’t read the account, gets 503 with no code: try again.