---
search:
  tags:
    - Webhooks
    - PUT
seo:
  description: >-
    Registers the URL that receives lead events. The URL must be https.
    Reference for the PUT /api/webhooks endpoint in the Comarketing API.
sidebar:
  label: Register a webhook
  badge: PUT
title: Register a webhook
type: openapi-operation
---
Registers the URL that receives lead events. The URL must be `https`.

The first PUT is `201` and returns the URL and the signing `secret`. Later PUTs replace the URL, keep the same secret, and return only the URL. A lost first response is not shown again. Integrations shows the URL and does not show the secret.

Events are not sent for the submit itself. They are sent when a queued lead is accepted (`lead.delivered`), when status changes (`lead.status_changed`), and when a queued lead is declined (`lead.declined`). The account that sent the lead receives the event, and so does each parent account that has a webhook, for leads in that parent's Leads Sent scope.

Delivery is at least once. A failed POST keeps the same `id` and is retried after two minutes, up to 8 attempts, without waiting for another lead. Verify the signature over the raw body before trusting the JSON.

`PUT /api/webhooks`

**Request body** (`application/json`, required)

- `url` (string<uri>, required) — Must be an \`https\` URL.

Request body example:

```json
{
  "url": "https://example.com/hooks"
}
```

**Responses**

- `200` — The URL was replaced. The signing secret is unchanged and is not returned.
- `201` — The webhook was created. Store the secret. It is not shown again.
- `401` — The key is missing or unknown.
- `403` — The key cannot send leads.
- `422` — The body is invalid, or the URL is not \`https\`.

Response example, 200:

```json
{
  "url": "https://example.com/hooks"
}
```

Response example, 201:

```json
{
  "url": "https://example.com/hooks",
  "secret": "signing_secret"
}
```

Response example, 401:

```json
{
  "error": "Invalid API key."
}
```

Response example, 403:

```json
{
  "error": "This key cannot send leads."
}
```

Response example, 422:

```json
{
  "error": "url must be an https URL."
}
```