Webhooks

Webhooks let your application react when supported events occur in Kurrier. Register and manage subscriptions from trusted server-side code using a Kurrier API key.

For authentication and the hosted API base URL, see API Authentication.

All management paths below are relative to:

https://YOUR_KURRIER_HOST/api/kurrier

Supported events

Kurrier currently supports:

message.received

The following event names are planned but are not yet available:

message.sent
message.delivered
message.bounced

Subscribe only to events listed as currently supported. For questions about additional events, contact Kurrier Support.

Create a webhook

`POST /webhooks`

{
  "ownerId": "be7a7201-76db-4b73-a5e0-ad6a1b93cf1f",
  "identityId": "1a9b317a-8a84-493a-b9f8-83a3800861e2",
  "url": "https://app.example.com/api/webhooks/kurrier",
  "events": ["message.received"],
  "description": "Process incoming support mail"
}

Field	Description	Example
url (required)	Public HTTPS endpoint that will receive event requests.	`"https://app.example.com/api/webhooks/kurrier"`
events (required)	Supported event names to subscribe to.	`["message.received"]`
ownerId (required)	User ID associated with the API key. Retrieve it with `GET /me`.	`"be7a7201-76db-4b73-a5e0-ad6a1b93cf1f"`
identityId	Restrict delivery to one accessible Kurrier identity. Omit it to receive subscribed events for all identities available to the subscription.	`"1a9b317a-8a84-493a-b9f8-83a3800861e2"`
enabled	Whether delivery is active. Defaults to `true`.	`true`
description	Label describing the integration.	`"Process incoming support mail"`

The API key must have access to the selected identity.

List webhooks

`GET /webhooks`

Returns webhook subscriptions available to the authenticated user.

Get a webhook

`GET /webhooks/{id}`

Returns one accessible webhook subscription by ID.

Update a webhook

`PATCH /webhooks/{id}`

Partially updates a webhook. Send only the fields you want to change. Set enabled to false when you need to pause delivery without deleting the subscription.

Delete a webhook

`DELETE /webhooks/{id}`

Permanently deletes the subscription.

Delivery format

Kurrier sends an HTTP POST request containing the event and its data:

{
  "event": "message.received",
  "data": {
    "message": {},
    "rawEmail": "..."
  }
}

The exact contents of data depend on the event.

Endpoint recommendations

Use a public HTTPS URL. Kurrier cannot deliver to localhost or a private development address.
Return a successful response promptly and move slow processing to a background job.
Treat deliveries as untrusted input and validate the event name and payload before processing them.
Make event handling idempotent so repeated delivery does not create duplicate work.
Keep sensitive message data out of application logs.
Disable or delete subscriptions that are no longer used.

Webhooks

On this page