# Register a webhook endpoint

> Register an HTTPS URL to receive per-photo batch results and verified collection-deletion completion events. (POST /v1/webhooks)

Source: https://sightradar.com/docs/api/webhooks/register-a-webhook-endpoint

Register an HTTPS URL to receive per-photo batch results and verified
collection-deletion completion events. We sign every delivery with
HMAC-SHA256 over `timestamp.body`. If you omit `secret`, one is generated
and returned **once**. Callback bodies are either
BatchWebhookEvent or
DeletionWebhookEvent.

### Example request

```bash
curl -X POST "https://api.sightradar.com/v1/webhooks" \
  -H "Authorization: Bearer $SR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.example.com/sightradar/webhook"}'
```

### Request body (application/json)

| Field              | Type     | Description                                    |
| ------------------ | -------- | ---------------------------------------------- |
| `url` **required** | `string` | Public HTTPS URL.                              |
| `secret`           | `string` | Optional signing secret; generated if omitted. |

### Response body

| Field                 | Type     | Description                        |
| --------------------- | -------- | ---------------------------------- |
| `webhook_endpoint_id` | `string` |                                    |
| `url`                 | `string` |                                    |
| `status`              | `string` |                                    |
| `secret`              | `string` | Returned ONCE only when generated. |
| `note`                | `string` |                                    |

### Status codes

| Status | Meaning                                |
| ------ | -------------------------------------- |
| `200`  | Endpoint registered.                   |
| `400`  | Invalid or non-HTTPS/private URL.      |
| `401`  | Missing or invalid API key.            |
| `503`  | Webhook encryption key not configured. |