Send events to custom webhook ingestion

Post Alertmanager notifications or generic events to the Developer API, and read the stored event ids.

Custom webhook ingestion gives your team one authenticated endpoint for events that other systems produce. This guide posts an Alertmanager notification and a generic JSON event, and shows how the response reports what was stored.

Before you start

You need an API key with the webhooks manage capability and the webhook.event.ingest action grant. The route takes no team id: events are recorded for the team the key resolves to, so the key must be bound to that team. See API keys to create one, and API overview for the capability levels and action grants.

Set the origin and key once for the examples:

export API_ORIGIN="https://api.openfactor.ai"
export API_KEY="<your API key>"

Steps

1. Post an Alertmanager notification

POST /v1/webhooks/custom accepts any JSON body. A payload whose alerts field is an array of objects is parsed as an Alertmanager notification, and each alert becomes one stored event.

curl -sS -X POST "$API_ORIGIN/v1/webhooks/custom" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "4",
    "status": "firing",
    "receiver": "workflow-trigger",
    "groupKey": "{}:{alertname=\"HighErrorRate\"}",
    "commonLabels": { "severity": "critical" },
    "commonAnnotations": { "summary": "Error rate is above the threshold." },
    "alerts": [
      {
        "status": "firing",
        "labels": { "alertname": "HighErrorRate", "service": "api" },
        "annotations": { "runbook": "https://example.test/runbooks/errors" },
        "startsAt": "2026-11-17T09:00:00Z",
        "fingerprint": "a1b2c3"
      }
    ]
  }'

For each alert, the event type is alertmanager.<status>.<alertname>. status comes from the alert, then the notification, then notification; alertname comes from the alert's labels.alertname, then alert. A space in either value becomes an underscore. The event payload is the notification's group metadata (commonAnnotations, commonLabels, externalURL, groupKey, groupLabels, receiver, status, truncatedAlerts, version) merged with the alert object.

The external id is built from alertmanager, the alert's fingerprint or the notification's groupKey or <alertname>:<index>, the status, startsAt, and endsAt when the status is resolved.

An alerts array that is present but empty stores one group event instead, typed alertmanager.<status>, with the whole notification as its payload.

2. Post a generic event

A body without an alerts array is stored as one generic event. Name it with a header or with a field in the body:

curl -sS -X POST "$API_ORIGIN/v1/webhooks/custom" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-custom-event-type: deployment.completed" \
  -H "x-custom-event-id: deploy-2026-11-17-1" \
  -d '{ "environment": "production", "revision": "a1b2c3d" }'

The event type is read from x-custom-event-type, then x-event-type, then the body's eventType, then the body's type, and defaults to custom.received. The external id is read from x-custom-event-id, then x-event-id, then the body's externalId, eventId, or id, and defaults to null. Header and body values are trimmed, and a blank value is ignored. The generic event type is stored as written; only the Alertmanager event type normalizes whitespace.

3. Read the response

The success response is 200 with the count accepted from this request and the stored event ids:

{
  "ok": true,
  "ingested": 1,
  "eventIds": ["b6f1c0a2-4f7e-4f2a-9d2f-0f6a1c3e5d7b"]
}

ingested counts the events in this request, including one whose external id already exists. An event with an external id is deduplicated for the team and source: posting the same external id again returns the existing event id instead of storing a second event. An event with no external id is stored on every delivery.

4. Respect the request limits

One request may contain at most 500 events. Split a larger batch across requests. Each event is stored separately, so a large batch is bounded by that cap, not by the response size.

Errors

StatusError valueWhen
400-The body is not valid JSON.
400-The request contains more than 500 events.
401-The request is missing a valid API key.
403-The key lacks the capability, the grant, or team access.

A 400 response stores no events. A storage failure after validation can leave earlier events from the same request stored, so retry with the same external ids and let deduplication return the ids that already exist.

Next steps