---
updatedAt: 2025-12-31T20:17:22.000Z
agentTools:
  projectIndex: https://developer.breezy.hr/llms.txt
---

# Webhook Management API

<br />

<br />

The Webhook Management API allows you to create, update, and delete webhook endpoints programmatically.

> **Note**
>
> All webhook management endpoints require authentication. See [Authorization](https://developer.breezy.hr/reference/authorization) for details.

## Endpoint Object

```json
{
    "id" : String,
    "url" : String,
    "description" : String,
    "events" : Array,
    "status" : String,
    "enabled" : Boolean,
    "stats" : {
        "successful_deliveries" : Number,
        "failed_deliveries" : Number,
        "last_delivery_at" : Date
    },
    "secret_prefix" : String,
    "created_at" : Date,
    "updated_at" : Date,
    "is_legacy" : Boolean
}
```

| Field           | Description                                    |
| --------------- | ---------------------------------------------- |
| `id`            | Unique identifier for the endpoint             |
| `url`           | HTTPS URL where webhooks will be delivered     |
| `description`   | Optional description of the endpoint           |
| `events`        | Array of event types to subscribe to           |
| `status`        | Current status: `active` or `paused`           |
| `enabled`       | Whether the endpoint is enabled for delivery   |
| `stats`         | Delivery statistics for the endpoint           |
| `secret_prefix` | Prefix of the shared secret (`whsec_`)         |
| `created_at`    | When the endpoint was created                  |
| `updated_at`    | When the endpoint was last modified            |
| `is_legacy`     | `true` if this is a legacy webhook (read-only) |

> **Note**
>
> The full `secret` is only returned when creating a new endpoint. Store it securely as it cannot be retrieved later.

***

## List Webhook Endpoints

Returns all webhook endpoints for a company.

```
GET /v3/company/{company_id}/webhook_endpoints
```

### Request

```bash
curl -X GET https://api.breezy.hr/v3/company/{company_id}/webhook_endpoints \
  -H "Authorization: {your_api_token}"
```

### Response

```json
{
    "data" : [
        {
            "id" : "abc123",
            "url" : "https://example.com/webhook",
            "description" : "Production webhook",
            "events" : ["candidateAdded", "candidateStatusUpdated"],
            "status" : "active",
            "enabled" : true,
            "stats" : {
                "successful_deliveries" : 42,
                "failed_deliveries" : 1,
                "last_delivery_at" : "2025-01-15T10:30:00Z"
            },
            "secret_prefix" : "whsec_",
            "created_at" : "2025-01-01T00:00:00Z",
            "updated_at" : "2025-01-15T10:30:00Z"
        }
    ]
}
```

***

## Get Webhook Endpoint

Returns a single webhook endpoint by ID.

```
GET /v3/company/{company_id}/webhook_endpoint/{endpoint_id}
```

### Request

```bash
curl -X GET https://api.breezy.hr/v3/company/{company_id}/webhook_endpoint/{endpoint_id} \
  -H "Authorization: {your_api_token}"
```

### Response

```json
{
    "id" : "abc123",
    "url" : "https://example.com/webhook",
    "description" : "Production webhook",
    "events" : ["candidateAdded", "candidateStatusUpdated"],
    "status" : "active",
    "enabled" : true,
    "stats" : {
        "successful_deliveries" : 42,
        "failed_deliveries" : 1,
        "last_delivery_at" : "2025-01-15T10:30:00Z"
    },
    "secret_prefix" : "whsec_",
    "created_at" : "2025-01-01T00:00:00Z",
    "updated_at" : "2025-01-15T10:30:00Z"
}
```

***

## Create Webhook Endpoint

Creates a new webhook endpoint.

```
POST /v3/company/{company_id}/webhook_endpoints
```

### Request Body

| Field         | Type   | Required | Description                    |
| ------------- | ------ | -------- | ------------------------------ |
| `url`         | String | Yes      | HTTPS URL for webhook delivery |
| `description` | String | No       | Description of the endpoint    |
| `events`      | Array  | Yes      | Event types to subscribe to    |

### Available Events

* `candidateAdded`
* `candidateDeleted`
* `candidateStatusUpdated`
* `companyPositionAdded`
* `companyPositionUpdated`
* `companyPositionDeleted`
* `companyPositionStateUpdated`
* `companyNotePosted`
* `companyNoteUpdated`
* `companyNoteDeleted`

### Request

```bash
curl -X POST https://api.breezy.hr/v3/company/{company_id}/webhook_endpoints \
  -H "Authorization: {your_api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "description": "Production webhook",
    "events": ["candidateAdded", "candidateStatusUpdated"]
  }'
```

### Response

```json
{
    "id" : "abc123",
    "url" : "https://example.com/webhook",
    "description" : "Production webhook",
    "events" : ["candidateAdded", "candidateStatusUpdated"],
    "status" : "active",
    "enabled" : true,
    "stats" : {
        "successful_deliveries" : 0,
        "failed_deliveries" : 0,
        "last_delivery_at" : null
    },
    "secret" : "whsec_abc123def456...",
    "created_at" : "2025-01-01T00:00:00Z",
    "updated_at" : "2025-01-01T00:00:00Z"
}
```

> **Important**
>
> Save the `secret` value immediately. It is only returned on creation and cannot be retrieved later. You will need it to verify webhook signatures.

### Errors

| Status | Error                                | Description                           |
| ------ | ------------------------------------ | ------------------------------------- |
| 400    | Invalid URL format                   | The URL is not valid                  |
| 400    | URL must use HTTPS protocol          | Only HTTPS URLs are allowed           |
| 400    | Events must be an array              | The events field must be an array     |
| 400    | At least one event must be specified | Events array cannot be empty          |
| 400    | Invalid events                       | One or more event types are not valid |
| 429    | Quota exceeded                       | Maximum of 10 endpoints per owner     |

***

## Update Webhook Endpoint

Updates an existing webhook endpoint.

```
PUT /v3/company/{company_id}/webhook_endpoint/{endpoint_id}
```

### Request Body

| Field         | Type    | Required | Description                     |
| ------------- | ------- | -------- | ------------------------------- |
| `url`         | String  | No       | HTTPS URL for webhook delivery  |
| `description` | String  | No       | Description of the endpoint     |
| `events`      | Array   | No       | Event types to subscribe to     |
| `enabled`     | Boolean | No       | Whether the endpoint is enabled |

### Request

```bash
curl -X PUT https://api.breezy.hr/v3/company/{company_id}/webhook_endpoint/{endpoint_id} \
  -H "Authorization: {your_api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["candidateAdded", "candidateDeleted", "candidateStatusUpdated"],
    "enabled": true
  }'
```

### Response

Returns the updated endpoint object.

```json
{
    "id" : "abc123",
    "url" : "https://example.com/webhook",
    "description" : "Production webhook",
    "events" : ["candidateAdded", "candidateDeleted", "candidateStatusUpdated"],
    "status" : "active",
    "enabled" : true,
    "stats" : {
        "successful_deliveries" : 42,
        "failed_deliveries" : 1,
        "last_delivery_at" : "2025-01-15T10:30:00Z"
    },
    "secret_prefix" : "whsec_",
    "created_at" : "2025-01-01T00:00:00Z",
    "updated_at" : "2025-01-20T14:00:00Z"
}
```

***

## Delete Webhook Endpoint

Deletes a webhook endpoint.

```
DELETE /v3/company/{company_id}/webhook_endpoint/{endpoint_id}
```

### Request

```bash
curl -X DELETE https://api.breezy.hr/v3/company/{company_id}/webhook_endpoint/{endpoint_id} \
  -H "Authorization: {your_api_token}"
```

### Response

```json
{
    "success" : true
}
```

***

## Pause Webhook Endpoint

Pauses webhook delivery to an endpoint. The endpoint will not receive webhooks while paused.

```
POST /v3/company/{company_id}/webhook_endpoint/{endpoint_id}/pause
```

### Request

```bash
curl -X POST https://api.breezy.hr/v3/company/{company_id}/webhook_endpoint/{endpoint_id}/pause \
  -H "Authorization: {your_api_token}"
```

### Response

Returns the updated endpoint object with `status: "paused"`.

```json
{
    "id" : "abc123",
    "url" : "https://example.com/webhook",
    "status" : "paused",
    "enabled" : true,
    ...
}
```

***

## Resume Webhook Endpoint

Resumes webhook delivery to a paused endpoint.

```
POST /v3/company/{company_id}/webhook_endpoint/{endpoint_id}/resume
```

### Request

```bash
curl -X POST https://api.breezy.hr/v3/company/{company_id}/webhook_endpoint/{endpoint_id}/resume \
  -H "Authorization: {your_api_token}"
```

### Response

Returns the updated endpoint object with `status: "active"`.

```json
{
    "id" : "abc123",
    "url" : "https://example.com/webhook",
    "status" : "active",
    "enabled" : true,
    ...
}
```

***

## Quotas and Limits

| Limit                  | Value                         |
| ---------------------- | ----------------------------- |
| Endpoints per customer | 10                            |
| Endpoints per partner  | 10 (separate quota)           |
| URL protocol           | HTTPS only                    |
| Delivery timeout       | 30 seconds                    |
| Retry attempts         | 10 (with exponential backoff) |