Webhooks

Webhooks push events to your systems as they happen: an alert opens, a weekly sampling completes, a fix is verified, an order is attributed to an AI assistant… Instead of polling the API, you expose an HTTPS endpoint and Skoup calls it.

Typical uses: open a ticket in your tracker when a critical alert opens, post the weekly sampling results to a data warehouse, trigger an n8n or Zapier workflow, refresh a client dashboard.

Set up an endpoint

Expose an HTTPS URL

Your endpoint must accept POST requests with a JSON body, over HTTPS, on a publicly reachable host. Addresses resolving to private, loopback or link-local IPs are refused. To test from your machine, use a tunnel (ngrok, Cloudflare Tunnel…) — see Best practices.

Register it

In Settings → Developers → Webhooks, click Add endpoint, paste the URL, pick the event types to receive (or all of them) and, optionally, restrict it to some brands.

Or from the API, with a key holding the webhooks:write scope:


curl https://api.skoup.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/skoup",
    "enabled_events": ["alert.created", "alert.resolved", "sampling.completed"],
    "description": "Alerts to our ticketing"
  }'

The response contains the endpoint’s signing secret (whsec_…). The API returns it only in this response; it stays available in the dashboard behind a Reveal button.

Verify the signature

Every delivery is signed with the endpoint’s secret. Always verify it before trusting a payload — see Verifying signatures.

Answer 2xx quickly

Return any 2xx status within 10 seconds. Anything else — or a timeout — counts as a failure and is retried.

The event object

Every delivery is a POST whose body is an event:


{
  "id": "evt_8KpL3mQn6RsT9uVw2xYz4A",
  "object": "event",
  "type": "alert.created",
  "api_version": "v1",
  "created": "2026-09-21T02:47:12Z",
  "livemode": true,
  "brand": "br_2xKq8Fh3LmN9pQrT4vWy6Z",
  "data": {
    "object": {
      "id": "alrt_5TgH2kLm8NpQ3rSv6wXy9A",
      "object": "alert",
      "kind": "price_hallucination",
      "severity": "critical",
      "status": "new",
      "…": "…"
    }
  }
}

Field	Description
`id`	Unique ID of the event. The same event delivered twice keeps the same ID.
`type`	What happened, as `resource.action`. See Event types.
`api_version`	Version of the payload format. Always `v1` today.
`created`	When the event happened (UTC).
`livemode`	`false` for events produced in test mode.
`brand`	The brand concerned.
`data.object`	The object concerned, in the exact shape returned by the matching `GET` endpoint.
`data.previous_attributes`	On `*.updated` events, the previous values of the fields that changed.

HTTP headers

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Skoup-Webhooks/1.0`
`X-Skoup-Signature`	`t=…,v1=…` — see Verifying signatures
`X-Skoup-Event-Id`	The event ID (`evt_…`), to deduplicate.
`X-Skoup-Event-Type`	The event type, to route without parsing the body.
`X-Skoup-Delivery-Id`	The ID of this delivery attempt (`whd_…`).

Catching up with the Events API

Events are also available through the API for 30 days, which lets you catch up after an outage or reconcile periodically:


curl "https://api.skoup.ai/v1/events?type=alert.created&limit=100" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Webhooks tell you that something happened; the event carries a snapshot of the object at that moment. If you need the latest state, fetch the object with its ID.