# Webhook endpoints

Source: https://parasend.com/docs/api/webhooks

Parasend tells your system about events by sending a small JSON payload to your HTTPS endpoint; fetch the resource for its full state. Every request is signed with HMAC-SHA256 over `timestamp.body` in the `Parasend-Signature` header; refuse a timestamp more than 5 minutes old. Failed attempts are retried with exponential backoff for up to 3 days. An endpoint may also require Parasend to authenticate (`auth.mode`): `none` (the signature only, the default), `static_bearer`, or `oauth2_client_credentials` against your own identity provider. The signature is sent whatever the mode. Parasend connects from fixed IP addresses, so you can allow-list them.

## Endpoints

- [Add a webhook endpoint](https://parasend.com/docs/api/webhooks/create.md): `POST /v1/webhook_endpoints`
- [List webhook endpoints](https://parasend.com/docs/api/webhooks/list.md): `GET /v1/webhook_endpoints`
- [Retrieve a webhook endpoint](https://parasend.com/docs/api/webhooks/retrieve.md): `GET /v1/webhook_endpoints/{id}`
- [Update a webhook endpoint](https://parasend.com/docs/api/webhooks/update.md): `PATCH /v1/webhook_endpoints/{id}`
- [Delete a webhook endpoint](https://parasend.com/docs/api/webhooks/delete.md): `DELETE /v1/webhook_endpoints/{id}`
- [Send a test event](https://parasend.com/docs/api/webhooks/test.md): `POST /v1/webhook_endpoints/{id}/test`
- [Replay events](https://parasend.com/docs/api/webhooks/replay.md): `POST /v1/webhook_endpoints/{id}/replay`
- [List an endpoint's attempts](https://parasend.com/docs/api/webhooks/attempts.md): `GET /v1/webhook_endpoints/{id}/attempts`
- [Roll an endpoint's signing secret](https://parasend.com/docs/api/webhooks/roll-secret.md): `POST /v1/webhook_endpoints/{id}/roll_secret`

## The WebhookEndpoint object

- `id` (string, optional): The webhook endpoint's ID, starting `whk_`.
- `object` (string, optional): Always `webhook_endpoint`.
- `url` (string, optional): The address Parasend posts events to: HTTPS, on port 443, on a public host.
- `event_types` (array of string, optional): One of: `delivery.created`, `delivery.rejected`, `delivery.notified`, `delivery.opened`, `delivery.email_opened`, `delivery.auth_failed`, `delivery.confirmed`, `delivery.downloaded`, `delivery.delivered`, `delivery.reminded`, `delivery.bounced`, `delivery.expired`, `delivery.revoked`, `delivery.consignment_failed`, `delivery.evidence_sealed`, `delivery.evidence_timestamp_deferred`, `delivery.evidence_timestamp_recovered`, `delivery.paper_pending_approval`, `delivery.paper_dispatched`, `delivery.paper_failed`, `document.previewed`, `batch.finalized`, `batch.completed`, `lookup.completed`, `consent.granted`, `consent.withdrawn`, `invitation.sent`, `link.opened`, `otp.sent`, `otp.verified`, `otp.locked`, `secret.attached`, `secret.available`, `secret.revealed`, `secret.copied`, `secret.expired`, `secret.exhausted`, `secret.revoked`, `request.sent`, `request.opened`, `request.fulfilled`, `request.expired`, `request.closed`, `request.reopened`, `deletion.scheduled`, `recipient_domain.verified`, `recipient_domain.degraded`, `recipient_domain.failed`, `member.suspended`, `member.restored`, `member.removed`, `batch.cancelled`, `batch.policy_changed`, `delivery.policy_changed`, `email_sender.verified`, `email_sender.degraded`, `email_sender.failed`, `email_sender.restored`.
- `secret` (string · nullable, optional): HMAC signing secret. Present only in the creation response.
- `auth` (object, optional): How Parasend authenticates to your endpoint, in addition to the HMAC signature, which is always sent. Secrets are write-only: accepted on create and update, never returned. The endpoint shows `mode`, the settings that are not secret, and whether a secret is set.
  - `auth.mode` (string, required): none = HMAC only. static_bearer = an `Authorization` header carrying `Bearer <token>` with a customer-supplied token. oauth2_client_credentials = a token obtained from the customer's IdP by the client-credentials grant, cached until expiry, sent as the bearer. One of: `none`, `static_bearer`, `oauth2_client_credentials`. Default: `"none"`.
  - `auth.static_bearer` (object · nullable, optional): With `mode: static_bearer`: the `token` Parasend sends as `Authorization: Bearer <token>`, at most 4,096 characters (write-only; responses show `token_set`). null for any other mode.
    - `auth.static_bearer.token_set` (boolean, optional)
  - `auth.oauth2` (object · nullable, optional): With `mode: oauth2_client_credentials`: your token endpoint (`token_url`, HTTPS), `client_id`, `client_secret` (write-only; responses show `client_secret_set`), optional `scope` and `audience`, and `auth_style`. null for any other mode.
    - `auth.oauth2.token_url` (string · uri, optional): HTTPS only.
    - `auth.oauth2.client_id` (string, optional)
    - `auth.oauth2.client_secret_set` (boolean, optional)
    - `auth.oauth2.scope` (string · nullable, optional)
    - `auth.oauth2.audience` (string · nullable, optional)
    - `auth.oauth2.auth_style` (string, optional): One of: `client_secret_basic`, `client_secret_post`. Default: `"client_secret_basic"`.
- `status` (string, optional): `enabled`: events are sent to it. `disabled`: paused; new events are not queued for it, and pending retries are cancelled when they come due. One of: `enabled`, `disabled`.
- `created` (string · date-time, optional): When it was created, in ISO 8601 (UTC).
- `livemode` (boolean, optional): `true` in live mode, `false` in test mode.
- `description` (string · nullable, optional): Your own note about the endpoint.
- `created_by` (object · nullable, optional): Who created the endpoint: a person, or the holder of the API key used. null for endpoints created before this was recorded.
  - `created_by.user_id` (string, optional)
  - `created_by.name` (string · nullable, optional)
  - `created_by.via` (string, optional): One of: `portal`, `api_key`.
- `exhausted_events` (integer, optional): Events that ran out of retries and have not been replayed successfully. More than 0 marks the endpoint in the portal.
- `last_exhausted_at` (string · date-time · nullable, optional): When an event last ran out of retries on this endpoint, in ISO 8601 (UTC); null if none ever has.
- `retrying_events` (integer, optional): Events with at least one failed attempt whose retries are still running.
- `last_attempt` (object · nullable, optional): The endpoint's latest attempt, in brief; null before the first.
- `previous_secret_expires_at` (string · date-time · nullable, optional): Set for 24 hours after a roll; null otherwise.
- `delivery_sources` (object · nullable, optional): null: every delivery's events.

```json
{
  "id": "whk_01M6R27T4KCSN7M0CHFGVH7JRA",
  "object": "webhook_endpoint",
  "url": "https://hooks.fyrirtaeki.example/parasend",
  "event_types": [
    "delivery.notified",
    "delivery.confirmed",
    "delivery.evidence_sealed"
  ],
  "description": "Case system",
  "secret": null,
  "auth": {
    "mode": "none",
    "static_bearer": null,
    "oauth2": null
  },
  "delivery_sources": null,
  "status": "enabled",
  "livemode": false,
  "exhausted_events": 0,
  "last_exhausted_at": null,
  "retrying_events": 0,
  "last_attempt": null,
  "created_by": {
    "user_id": "usr_01M6R27SYD4B50414S0BZ4KBKR",
    "name": "Jóna Jónsdóttir",
    "via": "api_key"
  },
  "previous_secret_expires_at": null,
  "created": "2026-11-06T09:15:05.746Z"
}
```