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
| Status | Error value | When |
|---|---|---|
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
- API overview - authentication, capabilities, and endpoint families
- API keys - create, scope, and revoke a key
- Send a message to a Chat and follow the turn - start work from a Chat
- Workflow and Run lifecycle - what happens after an event starts work