Events and webhooks

Every change is recorded as an event and kept for 30 days. Read them from the events feed, or have them delivered to your own HTTPS endpoint as signed webhooks. How deliveries work and how to verify them: Webhooks.

• GET/v1/eventsList events
• GET/v1/events/{id}Get an event
• GET/v1/webhook-endpointsList webhook endpoints
• POST/v1/webhook-endpointsCreate a webhook endpoint
• PATCH/v1/webhook-endpoints/{id}Update a webhook endpoint
• DELETE/v1/webhook-endpoints/{id}Delete a webhook endpoint
• POST/v1/webhook-endpoints/{id}/testSend a test event
• POST/v1/webhook-endpoints/{id}/rotate-secretRotate the signing secret
• POST/v1/events/{id}/redeliverRedeliver an event

List events

GET/v1/events

Requires the scope webhooks:manage.

Available from phase 2

Changes of the last 30 days, deletions included, oldest first. Use it to pick up deletes that updated_after can't show.

Query parameters

typestring

Only this event type, for example ride.deleted.

created_afterISO 8601

Only events after this time.

limitinteger

Page size, 1 to 100. Default 25.

cursorstring

The next_cursor of the previous page.

Request

curl "https://api.ambula.nl/v1/events?type=ride.deleted" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "evt_7Ss1",
      "type": "ride.deleted",
      "data": {
        "id": "r_6Gp1"
      },
      "created_at": "2026-11-09T11:00:00Z"
    }
  ],
  "next_cursor": "WzE3MzEx…"
}

Get an event

GET/v1/events/{id}

Requires the scope webhooks:manage.

Available from phase 2

One event, as it was delivered.

Request

curl "https://api.ambula.nl/v1/events/evt_7Ss1" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "id": "evt_7Ss1",
  "type": "ride.deleted",
  "data": {
    "id": "r_6Gp1"
  },
  "created_at": "2026-11-09T11:00:00Z"
}

List webhook endpoints

GET/v1/webhook-endpoints

Requires the scope webhooks:manage.

Available from phase 3

The company's webhook endpoints. The signing secret is never returned.

Request

curl "https://api.ambula.nl/v1/webhook-endpoints" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 200

{
  "data": [
    {
      "id": "we_1Hd8",
      "url": "https://bi.example.nl/ambula/webhooks",
      "events": [
        "ride.created",
        "ride.status_changed"
      ],
      "enabled": true,
      "created_at": "2026-11-09T10:00:00Z"
    }
  ],
  "next_cursor": null
}

Create a webhook endpoint

POST/v1/webhook-endpoints

Requires the scope webhooks:manage.

Available from phase 3

Register an HTTPS URL for the events you choose, up to 10 endpoints per company. The response is the only time the signing secret is shown.

Body

urlstringrequired

An https:// URL. Private and local addresses are refused.

eventsstring[]required

Event types, for example ride.created. ride.* matches all ride events.

Request

curl -X POST "https://api.ambula.nl/v1/webhook-endpoints" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Idempotency-Key: 4f1c9a2e-…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bi.example.nl/ambula/webhooks","events":["ride.created","ride.status_changed"]}'

Response · 201

{
  "id": "we_1Hd8",
  "url": "https://bi.example.nl/ambula/webhooks",
  "events": [
    "ride.created",
    "ride.status_changed"
  ],
  "enabled": true,
  "created_at": "2026-11-09T10:00:00Z",
  "secret": "whsec_…"
}

Update a webhook endpoint

PATCH/v1/webhook-endpoints/{id}

Requires the scope webhooks:manage.

Available from phase 3

Change the URL or the events, or turn the endpoint off and on.

Body

urlstring

An https:// URL.

eventsstring[]

Event types.

enabledboolean

Pause or resume deliveries.

Request

curl -X PATCH "https://api.ambula.nl/v1/webhook-endpoints/we_1Hd8" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Response · 200

{
  "id": "we_1Hd8",
  "url": "https://bi.example.nl/ambula/webhooks",
  "events": [
    "ride.created",
    "ride.status_changed"
  ],
  "enabled": false,
  "created_at": "2026-11-09T10:00:00Z"
}

Delete a webhook endpoint

DELETE/v1/webhook-endpoints/{id}

Requires the scope webhooks:manage.

Available from phase 3

Stop delivering to this endpoint and forget it.

Request

curl -X DELETE "https://api.ambula.nl/v1/webhook-endpoints/we_1Hd8" \
  -H "Authorization: Bearer amb_live_<key>"

Response · 204, no body

Send a test event

POST/v1/webhook-endpoints/{id}/test

Requires the scope webhooks:manage.

Available from phase 3

Deliver a signed ping event to the endpoint, to check your receiver.

Request

curl -X POST "https://api.ambula.nl/v1/webhook-endpoints/we_1Hd8/test" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Idempotency-Key: 4f1c9a2e-…"

Response · 200

{
  "delivered": true,
  "status": 200,
  "duration_ms": 142
}

Rotate the signing secret

POST/v1/webhook-endpoints/{id}/rotate-secret

Requires the scope webhooks:manage.

Available from phase 3

Issue a new signing secret. For 24 hours both secrets sign each delivery, so you can switch without missing one.

Request

curl -X POST "https://api.ambula.nl/v1/webhook-endpoints/we_1Hd8/rotate-secret" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Idempotency-Key: 4f1c9a2e-…"

Response · 200

{
  "id": "we_1Hd8",
  "secret": "whsec_…",
  "previous_secret_expires_at": "2026-11-10T10:00:00Z"
}

Redeliver an event

POST/v1/events/{id}/redeliver

Requires the scope webhooks:manage.

Available from phase 3

Deliver an event to its endpoints again, for example after your receiver was down.

Request

curl -X POST "https://api.ambula.nl/v1/events/evt_7Ss1/redeliver" \
  -H "Authorization: Bearer amb_live_<key>" \
  -H "Idempotency-Key: 4f1c9a2e-…"

Response · 202

{
  "queued": true
}