# Webhook endpoints

Creating and removing the endpoints that receive callbacks. What those
callbacks look like, and how to verify them, is in
[Webhooks](https://ydomain.com/docs/webhooks).

All three endpoints need the `webhooks:manage` ability.

| Method | Path |
| --- | --- |
| `GET` | `/webhooks` |
| `POST` | `/webhooks` |
| `DELETE` | `/webhooks/{webhook}` |

### List endpoints

```bash
curl https://ydomain.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

```json
{
  "data": [
    {
      "id": "01920fd8-2c19-7e44-b3a7-5d8e1f0c6b92",
      "name": "Zapier",
      "url": "https://example.com/hooks/ydomain",
      "events": ["lead.created", "domain.sold"],
      "is_active": true,
      "consecutive_failures": 0,
      "disabled_at": null,
      "last_delivered_at": "2026-09-16T21:40:02+00:00",
      "created_at": "2026-05-02T09:15:44+00:00"
    }
  ]
}
```

The signing secret is not in this response. It is returned once, when the
endpoint is created, and after that only in the account area.

### Create an endpoint

```bash
curl -X POST https://ydomain.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Zapier",
    "url": "https://example.com/hooks/ydomain",
    "events": ["lead.created", "lead.replied"]
  }'
```

| Field | Rules |
| --- | --- |
| `name` | Optional, max 120 |
| `url` | Required, a public HTTPS URL, max 2048 |
| `events` | Required, at least one event from the tables above |

`201 Created`, with the secret:

```json
{
  "data": {
    "id": "01920fd8-2c19-7e44-b3a7-5d8e1f0c6b92",
    "name": "Zapier",
    "url": "https://example.com/hooks/ydomain",
    "events": ["lead.created", "lead.replied"],
    "is_active": true,
    "secret": "whsec_kF4RbTWsCkyKi782Nk2qt4gKYBriPxCj1eRefzla",
    "created_at": "2026-09-17T08:31:12+00:00"
  }
}
```

Store that secret now. A URL that resolves to a private address is refused:

```json
{
  "message": "The url must be a publicly reachable address.",
  "errors": { "url": ["The url must be a publicly reachable address."] }
}
```

### Delete an endpoint

```bash
curl -X DELETE https://ydomain.com/api/v1/webhooks/01920fd8-2c19-7e44-b3a7-5d8e1f0c6b92 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

```http
HTTP/1.1 204 No Content
```