Webhooks

A signal webhook is an endpoint you create that anything able to POST JSON can send to: a support tool, an alerting channel, a cron job, an internal admin tool. Each endpoint has its own secret and its own budget. Each accepted delivery becomes a signal (or updates one, for an incident), the first stage of the loop.

Webhook operations

Paths are relative to https://api.getnima.io. No operation on this page carries an OAuth scope, and there is no MCP tool for webhooks. See authentication for the other credentials.

Creating a webhook endpoint

A webhook endpoint is created with POST /v1/signal-webhooks from a signed-in owner or admin session. There is no admin-panel control for it: use the call below with the app's session token, or ask the nima team to create one. A workspace holds at most 10 endpoints.

The response carries a URL id and a secret that starts with nwh_. The secret is shown once, at creation and at rotation. nima stores only a hash, so a lost secret can only be replaced by rotating. The endpoint URL is:

https://api.getnima.io/v1/webhooks/signals/<id>

An API key or an OAuth access token cannot manage endpoints: those routes declare no scope, so such a token gets 403. The add call has the details.

Send a signal to a webhook endpoint

Send a webhook secret as a Basic auth password

Send the secret as the Basic auth password when the sender cannot set headers. The username is ignored.

curl -X POST https://api.getnima.io/v1/webhooks/signals/6f1c0b84-53a7-4e29-8d15-2c7a9e0b43f6 \
  -u "nima:$NIMA_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bulk export times out on large workspaces"}'

What nima does with webhook JSON

nima flattens the JSON body into key: value lines, redacts them, and runs the result through the same classify, extract and embed pass as a Slack thread. The raw body is not stored. The signal is created with source webhook, and its origin is internal.

Nested objects become dotted keys, so {"customer":{"name":"Northwind"}} reads as customer.name: Northwind. Flattening stops at these limits, and anything past them is dropped, so put what matters near the top of the object:

For a body without a top-level incident object, the headline of the signal is the first of title, summary, message, description, text, name and subject that is present. For an incident body, the headline is the policy name plus the summary. A top-level url or link that starts with http is kept as the signal's link, with query string, fragment and credentials stripped.

Redaction of webhook content

nima redacts webhook content before it is stored. nima drops any field named authorization, password, secret, token, access_token, refresh_token, api_key (also apikey, api-key) or cookie, at any level and in any letter case; inside arrays the value shows as [redacted]. The remaining text has these patterns replaced:

Redaction is pattern matching, not a guarantee. Do not send secrets you do not want nima to hold.

Webhook weight in beacon ranking

A webhook signal carries a producer weight of 0.8 when a beacon is ranked, the same as Sentry and PostHog, on the reasoning that an inbound webhook is usually your own alerting rather than one person's opinion. See How nima decides.

Webhook deduplication

nima deduplicates webhook deliveries for 24 hours, using the first of these keys that applies:

1. The Idempotency-Key header.
2. For a body that carries an incident object (read under triage if the body has a triage object, else under report, else at the top level): the incident id, the incident state, and the provider timestamp when there is one. An incident that opens and later closes gives two different keys.
3. A top-level id, event_id or eventId in the body.
4. A SHA-256 hash of the raw body.

A repeat inside the window answers { "accepted": false, "reason": "duplicate" }. The 24-hour window only decides the duplicate receipt. A repeat of the same key after that answers accepted: true, but it lands on the signal the key already created, so it never makes a second one. Deduplication is per endpoint: two endpoints sending the same id create two signals.

Send Idempotency-Key when you can: a retry of a delivery that failed in transit is then safe, and a body whose text changes slightly between retries does not create a second signal.

Incident alerts as one signal

An incident-shaped webhook body updates a single signal instead of creating one per notification. When the body has an incident object with an id, the signal is keyed on the endpoint plus a hash of the provider and incident id. The open and the later recovery notification both land on that one signal; a notification whose provider timestamp is older than the one nima already holds is ignored.

A body with a top-level incident object is also rendered as a Google Cloud Monitoring alert. nima renders it as a report (policy, condition, resource, project, observed and threshold values, documentation, start and end) instead of flat lines, and a closed incident is previewed as recovered.

Structured bug reports over webhooks

A webhook body can carry a structured bug report, either at the top level or nested under triage or report. nima reads these fields as evidence, marks it as reported and not verified, and lists what is missing:

Fingerprint of a webhook bug report

A bug report gets a stable fingerprint only when service, environment, message, an error type or code, and at least one application stack frame are all present. Nothing in that identity may be redacted or truncated. Line and column numbers are ignored when comparing frames. If any part is missing the report still becomes a signal, without a fingerprint.

Bug reports and beacons

A signal with a fingerprint joins the open beacon (forming, ready or held, or promoted to a spec that has not shipped) that has the same fingerprint and scope, without asking the placement judge. A dismissed beacon or one whose spec has shipped is never reopened: with no open match, the signal forms a new beacon marked as a fix rather than a product decision. See How nima decides for grouping in general.

A report is urgent when all of these hold: the severity (impact.severity, else the report's or incident's severity) is critical, high or fatal; the outcome (impact.outcome, else outcome) is failed, terminal_failure, retry_exhausted, data_loss or unavailable; the report has an error; and the incident is not marked recovered. An urgent report makes its beacon ready at once, without waiting for more evidence. Occurrence counts do not count towards urgency.

Webhook limits

Webhook limits are per endpoint, plus one per workspace and one on the transport.

A delivery dropped for being over budget adds to the endpoint's droppedCount; a duplicate does not. The count is visible only over the API (the list, add and rotate responses); the admin panel does not show it. Accepted deliveries are queued for processing with 3 attempts and exponential backoff.

Managing webhook endpoints over the API

The four management operations take a signed-in nima session and never a key. An API key or an OAuth access token answers 403. They carry no stability promise, and in the examples $NIMA_SESSION stands for the app's session token.

List webhook endpoints

Add a webhook endpoint

Rotate a webhook secret

Delete a webhook endpoint

The webhook endpoint object

A webhook endpoint object is one row per sender, each with its own secret and budget.