---
title: "Webhooks"
description: "Register HTTPS endpoints that receive signed event deliveries (delivered, bounced, opened, clicked, …). The signing secret is returned once on create; verify the signature on every delivery."
url: https://www.unitpost.com/docs/api/webhooks
section: API reference
updated: 2026-07-31
---
# Webhooks

## Webhooks

> Register HTTPS endpoints that receive signed event deliveries (delivered, bounced, opened, clicked, …). The signing secret is returned once on create; verify the signature on every delivery.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/api/webhooks.

## Operations

### `GET /api/v1/webhooks`

List webhook endpoints

Retrieve a list of your webhook endpoints, cursor-paginated, with each endpoint's URL, subscribed events, and status. Signing secrets are never returned here — they're shown exactly once by [Create a webhook endpoint](#post-webhooks). Check an endpoint's wiring end-to-end with [Send a test event](#post-webhooks-id-test). Requires the `webhooks:read` capability.

### `POST /api/v1/webhooks`

Create a webhook endpoint

Register an `https` URL to receive event notifications (deliveries, bounces, opens, clicks, and more) and choose which events it subscribes to. The response includes the `signing_secret` exactly once — store it now, as it can never be retrieved again; use it to verify each delivery's signature. Confirm the endpoint works with [Send a test event](#post-webhooks-id-test), and adjust its URL or events later with [Update a webhook endpoint](#patch-webhooks-id). Requires the `webhooks:manage` capability.

### `GET /api/v1/webhooks/{id}`

Retrieve a webhook endpoint

Retrieve a single webhook endpoint by `id` — its URL, subscribed events, and status. The signing secret is never included; it's returned exactly once when the endpoint is [created](#post-webhooks). Requires the `webhooks:read` capability.

### `PATCH /api/v1/webhooks/{id}`

Update a webhook endpoint

Update a webhook endpoint's `url`, subscribed `events`, `name`, and/or `status` (use `status` to pause and re-enable deliveries without deleting the endpoint). The signing secret is never changed by an update. Verify your changes with [Send a test event](#post-webhooks-id-test). Requires the `webhooks:manage` capability.

### `DELETE /api/v1/webhooks/{id}`

Delete a webhook endpoint

Permanently delete a webhook endpoint and its delivery log. Deliveries stop immediately. The operation is idempotent — deleting an already-deleted endpoint still returns `204`. To stop deliveries temporarily instead, set `status` via [Update a webhook endpoint](#patch-webhooks-id). Requires the `webhooks:manage` capability.

### `POST /api/v1/webhooks/{id}/test`

Send a test event

Fire a sample event at the endpoint synchronously and return the receiver's response so you can debug your handler end-to-end. The probe is signed exactly like a real delivery (verify it the same way) but is not persisted to the delivery log. Configure the endpoint itself with [Update a webhook endpoint](#patch-webhooks-id). Requires the `webhooks:manage` capability.

## Related

- [API keys](https://www.unitpost.com/docs/api/api-keys): Create and revoke the API keys your integrations authenticate with. These endpoints are session-gated (dashboard cookie + `apikeys:manage`) and NOT usable with a Bearer API key.
- [Suppressions](https://www.unitpost.com/docs/api/suppressions): Address-level send blocks — the hard "never email this address" list. Combines engine-written bounce/complaint entries, your own additions, and read-only Unitpost-wide blocks.
- [Usage](https://www.unitpost.com/docs/api/usage): Your workspace's current billing-period usage: emails sent, and on paid plans the dollar sending wallet (monthly allowance, spend, purchased credit, overage) in integer USD cents.