# Register a webhook endpoint

**POST** `/v1/webhook-endpoints`

Base URL: `https://api.parcel-events.example`

Tags: `Webhook endpoints`

## Authorization

Any ONE of the following options authorizes this operation; every scheme listed within an option is required together.

| Option | Scheme | Type | Sent as | Scopes |
| --- | --- | --- | --- | --- |
| Option 1 | `ApiKey` | `apiKey` | header `Parcel-API-Key` | — |
| Option 2 | `BearerToken` | `http` | `Authorization: Bearer <token>` (opaque) | — |

## Request body

Required. Media type: `application/json`

### Example request body

```json
{
  "description": "string",
  "events": [
    "pickup.completed"
  ],
  "url": "https://hooks.parcel-events.example/events"
}
```

## Responses

| Status | Description | Media type |
| --- | --- | --- |
| `201` | Webhook endpoint registered | `application/json` |
| `422` | One or more fields failed semantic validation | `application/problem+json` |

### Example response: 201 — Webhook endpoint registered

```json
{
  "created_at": "2026-06-09T00:00:00Z",
  "enabled": true,
  "events": [
    "pickup.completed"
  ],
  "id": "whe_00000000000000000001",
  "object": "webhook_endpoint",
  "signing_secret_hint": "synthetic-key-ending-0000",
  "url": "https://hooks.parcel-events.example/events"
}
```

### Example response: 422 — One or more fields failed semantic validation

```json
{
  "errors": [
    {
      "message": "must be a synthetic postal code",
      "path": "recipient.postal_code"
    }
  ],
  "request_id": "req_00000000000000000006",
  "status": 422,
  "title": "Synthetic request validation failed",
  "type": "https://parcel-events.example/problems/validation"
}
```

## Related pages

- [Buy and render a shipping label](./createlabel.md)
- [Cancel a pickup](./cancelpickup.md)
- [Cancel a shipment before handoff](./cancelshipment.md)
- [Create a shipment](./createshipment.md)
- [Delete a webhook endpoint](./deletewebhookendpoint.md)
- [Labels](./tags/labels.md)
- [List scheduled pickups](./listpickups.md)
- [List shipments](./listshipments.md)
- [List tracking events for a shipment](./listshipmentevents.md)
- [List webhook endpoints](./listwebhookendpoints.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.