Webhook Management API

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

Note

All webhook management endpoints require authentication. See Authorization for details.

Endpoint Object

{
    "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

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

Response

{
    "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

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

Response

{
    "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

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

{
    "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

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.

{
    "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

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

Response

{
    "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

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".

{
    "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

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".

{
    "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)