# Webhooks

> Receive attack events from the OpenShield agent's alerter and ticket notifications from the console, and verify delivery from the metrics payload.
>
> Canonical: https://xdp.network/docs/api-reference/webhooks · Updated 2026-08-09

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:

```bash
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:

```json title="Ticket notification"
{
  "kind": "...",
  "title": "...",
  "body": "...",
  "ticket_ref": "..."
}
```

`ticket_ref` identifies the ticket the notification is about. You manage the URL per
account in the dashboard.

:::tip
Keep your webhook endpoints fast. The alerter queues events when the endpoint responds
slowly and drops them under sustained backpressure — watch `alerter.queued` and
`alerter.dropped` in the metrics payload. Acknowledge quickly and do any heavy
processing out of band.
:::

## Next steps

- [Enabling metrics](/docs/openshield-xdp/enabling-metrics)
- [Endpoints](/docs/api-reference/endpoints)
- [Errors](/docs/api-reference/errors)