Webhooks
Receive attack events from the OpenShield agent's alerter and ticket notifications from the console, and verify delivery from the metrics payload.
Last updated
On this page
Two webhook kinds exist, and they come from different places: the OpenShield agent on your server sends attack-event webhooks, and the console sends ticket notifications to a per-account URL. Both push to you, so neither requires polling.
Agent attack-event webhooks
The agent's alerter POSTs attack events to a webhook URL you choose, directly from
your server — this traffic does not pass through the console. Configure it with the
alerter.* keys in /etc/openshield/openshield.yaml, then apply the change:
openshield reload
Verify delivery from the metrics payload
GET /metrics reports the alerter's state, so you can confirm the integration without
waiting for an attack:
| Field | Meaning |
|---|---|
alerter.webhook_set | A webhook URL is configured |
alerter.queued | Events waiting to be delivered |
alerter.sent | Events delivered successfully |
alerter.dropped | Events discarded before delivery |
alerter.last_success_at | Timestamp of the last successful delivery |
alerter.last_error | The most recent delivery error |
When events stop arriving, read alerter.last_error first — it tells you whether the
problem is reaching your endpoint or in the response your endpoint returned.
Console ticket notifications
The console can POST a JSON notification to a webhook URL set on your account whenever ticket activity occurs. The body looks like this:
{
"kind": "...",
"title": "...",
"body": "...",
"ticket_ref": "..."
}
ticket_ref identifies the ticket the notification is about. You manage the URL per
account in the dashboard.