Event forwarding API

These endpoints manage where your events are forwarded: the HTTPS destinations on Settings > Event forwarding. They list, add, change and remove destinations, replace a signing secret, and send a test event. What is sent, the formats and the signature are explained in Event forwarding.

List destinations

GET /api/forwarding/ lists your destinations with their delivery counters, plus the choices a destination takes. It is a read.

GET /api/forwarding/

{
  "destinations": [
    { "id": 3, "name": "Splunk", "url": "https://splunk.example.com:8088/services/collector/event",
      "enabled": true, "min_severity": "medium", "agent_kinds": [], "format": "splunk_hec",
      "auth_header_name": "Authorization", "auth_header_set": true,
      "delivered_events": 1520, "delivered_batches": 311, "failed_events": 0, "dropped_events": 0,
      "last_success_at": "2026-10-19T09:12:03Z", "last_error_at": null, "last_error": "",
      "queued": 0, "created_at": "2026-10-18T14:00:00Z", "updated_at": "2026-10-18T14:00:00Z" }
  ],
  "max_destinations": 5,
  "formats": ["json", "ndjson", "splunk_hec"],
  "severities": ["info", "low", "medium", "high", "critical"],
  "agent_kinds": [ { "kind": "python", "name": "es-python" } ],
  "signature_header": "X-EyalSec-Signature"
}

Secrets are never returned. auth_header_set says whether an auth header value is stored. queued is how many events are waiting to be sent right now.

Add a destination

POST /api/forwarding/ adds a destination and answers 201 with it and its signing_secret. The secret is shown this once, so store it where your receiver can read it.

POST /api/forwarding/

JSON body:

curl -s -X POST https://eyalsec.com/api/forwarding/ \
  -H "X-API-Key: es2_EXAMPLEKEYdoNotUse0000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://splunk.example.com:8088/services/collector/event","format":"splunk_hec","auth_header_name":"Authorization","auth_header_value":"Splunk <hec-token>"}'

{ "destination": { "id": 3, "url": "https://splunk.example.com:8088/services/collector/event", "...": "..." },
  "signing_secret": "esfwd_..." }

A private, loopback, link-local or cloud metadata address, a plain http:// address, or a host that cannot be found answers 400 with the reason. A sixth destination answers 409.

Change a destination

PATCH /api/forwarding/{id}/ changes the fields the body names, with the same fields as above, and answers with the destination. Fields you leave out keep their values. A new url is checked again.

curl -s -X PATCH https://eyalsec.com/api/forwarding/3/ \
  -H "X-API-Key: es2_EXAMPLEKEYdoNotUse0000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"min_severity":"high"}'

Send auth_header_value to replace the stored value. An empty auth_header_name removes the header. Another account's id answers 404.

Remove a destination

DELETE /api/forwarding/{id}/ removes a destination and answers 204. Events still waiting to be sent to it are discarded.

Replace the signing secret

POST /api/forwarding/{id}/secret/ makes a new signing secret and answers {"signing_secret": "esfwd_..."}, shown this once. The old secret stops being used at once.

Send a test event

POST /api/forwarding/{id}/test/ sends one test event now, signed like a real delivery and marked "test": true, and reports what the destination answered. It is tried once, with no retry, and works on a paused destination.

{ "ok": true, "status": 200, "error": "", "latency_ms": 184 }

When the destination refuses or cannot be reached, ok is false and error says why. One test per destination every 5 seconds; sooner answers 429.