Webhooks

Attach a webhook and the monitor tells you when a run finishes, so you do not have to poll.

Attach a webhook

The webhook is a single message: a url, an events list, and a status. The two legal events are run.completed and run.failed, and the list must name at least one. run.completed fires whenever any search request succeeded, so it covers a partial run too; only a run where every request failed sends run.failed, and a skipped run sends nothing. Read the run’s status to tell which — see Reference. status may be omitted at create time; the server sets the webhook active.

from seltz import Seltz

client = Seltz()

response = client.monitor.create(
    "my-webhook-monitor",
    cadence="6h",
    search_requests=["best ai search engines"],
    webhook={
        "url": "https://example.com/seltz/monitors",
        "events": ["run.completed", "run.failed"],
    },
)

monitor_id = response.monitor.monitor_id

# Returned once, at create, and never again.
print(response.webhook_secret)

import { Seltz } from "seltz";

const client = new Seltz();

const response = await client.monitor.create({
  name: "my-webhook-monitor",
  cadence: "6h",
  searchRequests: ["best ai search engines"],
  webhook: {
    url: "https://example.com/seltz/monitors",
    events: ["run.completed", "run.failed"],
  },
});

const monitorId = response.monitor!.monitorId;

// Returned once, at create, and never again.
console.log(response.webhookSecret);

curl -X POST https://api.seltz.ai/v1/monitors \
  -H "x-api-key: $SELTZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-webhook-monitor",
    "cadence": "6h",
    "search_requests": [{"query": "best ai search engines"}],
    "webhook": {
      "url": "https://example.com/seltz/monitors",
      "events": ["run.completed", "run.failed"]
    }
  }'

webhook_secret is returned once, in the create response, and never again. Store it when you create the monitor. There is currently no way to rotate it. See Reference.

Deliveries

The request body is {"event": ..., "run": ...}. It carries the run, not the records — fetch those with the record cursor described in Read records. The run is the same object GET /v1/monitors/{monitor_id}/runs/{run_id} returns; the example below shows only some of its fields.

{
  "event": "run.completed",
  "run": {
    "run_id": "1740000000000000001",
    "record_count": 12,
    "requests_ok": 2,
    "requests_total": 2
  }
}

A delivery can arrive more than once. Each delivery is one run, so make your handler idempotent on run_id. Deliveries are signed following the Standard Webhooks specification. Each one carries three headers:

webhook-id: 88422335203246080
webhook-timestamp: 1740000000
webhook-signature: v1,<base64>

Verify a delivery

Verify before trusting the payload. Use the Standard Webhooks library for your language — one exists for Python, JavaScript, Go, Rust, Java, Kotlin, Ruby, PHP, C# and Elixir — and pass it the secret, the raw request body and the headers. Verification runs in your handler, so there is no cURL form.

from standardwebhooks import Webhook

payload = Webhook(secret).verify(body, headers)

import { Webhook } from "standardwebhooks";

const payload = new Webhook(secret).verify(body, headers);

The library checks the signature and the timestamp together, so a captured delivery cannot be replayed later. It raises rather than returning a value when verification fails; answer 401 and do not process the payload.

Pass the raw body — the bytes as received. A framework that hands you a parsed object has already discarded what the signature covers, so reach for the raw-body accessor yours provides.

When deliveries keep failing

Failed deliveries are retried with backoff. A webhook that keeps failing is set to disabled. What is disabled is the webhook, not the monitor. The monitor keeps running on its cadence and keeps collecting records; you read them with the record cursor, and re-enable the webhook with an ordinary update once your endpoint is healthy. There is no notification when this happens — check webhook.status if deliveries stop arriving.

Disable, enable and remove

Disabling and enabling a webhook are ordinary update calls that set its status. The whole Webhook message is replaced, so resend url and events alongside the new status — omitting them does not preserve them.

from seltz import WebhookStatus

client.monitor.update(
    monitor_id,
    webhook={
        "url": "https://example.com/seltz/monitors",
        "events": ["run.completed", "run.failed"],
        "status": WebhookStatus.WEBHOOK_STATUS_DISABLED,
    },
)

import { WebhookStatus } from "seltz";

await client.monitor.update(monitorId, {
  webhook: {
    url: "https://example.com/seltz/monitors",
    events: ["run.completed", "run.failed"],
    status: WebhookStatus.DISABLED,
  },
});

MONITOR_ID="your-monitor-id"

curl -X PATCH "https://api.seltz.ai/v1/monitors/$MONITOR_ID" \
  -H "x-api-key: $SELTZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "url": "https://example.com/seltz/monitors",
      "events": ["run.completed", "run.failed"],
      "status": "disabled"
    }
  }'

Enabling is the same call with the active status. To remove the webhook entirely, send null:

client.monitor.update(monitor_id, webhook=None)

await client.monitor.update(monitorId, { webhook: null });

MONITOR_ID="your-monitor-id"

curl -X PATCH "https://api.seltz.ai/v1/monitors/$MONITOR_ID" \
  -H "x-api-key: $SELTZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook": null}'

Removing the webhook does not retire the secret, and re-adding one does not issue a new one. Omitting webhook on an update keeps it; null removes it — see Reference.

Getting Started

Web Tools

Data

Tutorials

Chat

Integrations

SDKs

Attach a webhook

Deliveries

Verify a delivery

When deliveries keep failing

Disable, enable and remove

​Attach a webhook

​Deliveries

​Verify a delivery

​When deliveries keep failing

​Disable, enable and remove

Attach a webhook

Deliveries

Verify a delivery

When deliveries keep failing

Disable, enable and remove