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

# Customer Guide

This guide walks you through setting up and managing webhooks for your Breezy account.

> **Note**
>
> Webhook functionality is available for Pro plans. Please contact <support@breezy.hr> for details.

## Prerequisites

Before you begin, you'll need:

1. A Breezy Pro account
2. An API access token (see [Authorization](https://developer.breezy.hr/reference/authorization))
3. A publicly accessible HTTPS endpoint to receive webhooks

## Getting Your Company ID

Most webhook API calls require your company ID. You can find it by:

1. Calling the companies endpoint:

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

2. The response includes your company ID:

```json
[
    {
        "_id" : "abc123def456",
        "name" : "Your Company Name",
        ...
    }
]
```

***

## Step 1: Create a Webhook Endpoint

Create an endpoint to start receiving webhooks:

```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://your-server.com/breezy-webhook",
    "description": "Production webhook receiver",
    "events": ["candidateAdded", "candidateStatusUpdated"]
  }'
```

### Response

```json
{
    "id" : "abc123",
    "url" : "https://your-server.com/breezy-webhook",
    "description" : "Production webhook receiver",
    "events" : ["candidateAdded", "candidateStatusUpdated"],
    "status" : "active",
    "enabled" : true,
    "secret" : "whsec_a1b2c3d4e5f6...",
    ...
}
```

> **Important**
>
> Save the `secret` value immediately! It is only shown once and cannot be retrieved later.

***

## Step 2: Set Up Your Receiver

Create an endpoint on your server to receive webhooks. Here's a simple Node.js example:

```javascript
const express = require('express')
const crypto = require('crypto')

const app = express()
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET // The secret from Step 1

app.post('/breezy-webhook', express.json(), (req, res) => {
  // Verify the signature
  const signature = req.headers['x-hook-signature']
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET)
  hmac.update(JSON.stringify(req.body))
  const calculated = hmac.digest('hex')
  
  if (!crypto.timingSafeEqual(Buffer.from(calculated), Buffer.from(signature))) {
    console.error('Invalid webhook signature')
    return res.status(401).json({ error: 'Invalid signature' })
  }
  
  // Process the webhook
  const { type, object } = req.body
  
  switch (type) {
    case 'candidateAdded':
      console.log('New candidate:', object.candidate.name)
      // Add your logic here
      break
    case 'candidateStatusUpdated':
      console.log('Candidate moved:', object.candidate.name, '->', object.stage.name)
      // Add your logic here
      break
  }
  
  res.status(200).json({ success: true })
})

app.listen(3000)
```

***

## Step 3: Test Your Setup

Trigger an event in Breezy to test your webhook:

1. Add a candidate to a position
2. Check your server logs for the incoming webhook
3. Verify the signature was validated successfully

***

## Managing Your Endpoints

### List All Endpoints

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

### View Delivery Stats

The response includes stats for each endpoint:

```json
{
    "stats" : {
        "successful_deliveries" : 42,
        "failed_deliveries" : 1,
        "last_delivery_at" : "2025-01-15T10:30:00Z"
    }
}
```

### Update Events

Add or remove events from an endpoint:

```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"]
  }'
```

### Pause an Endpoint

Temporarily stop webhook delivery:

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

### Resume an Endpoint

Resume webhook delivery:

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

### Delete an Endpoint

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

***

## Quotas

Each customer can create up to **10 webhook endpoints**. If you need more, contact <support@breezy.hr>.

***

## Troubleshooting

### Not Receiving Webhooks

1. **Check endpoint status** - Ensure status is "active" and enabled is true
2. **Check events** - Verify you're subscribed to the event type you're expecting
3. **Check your URL** - Ensure it's publicly reachable over HTTPS
4. **Check failed\_deliveries** - If this number is increasing, there may be an issue with your endpoint

### Signature Verification Failing

1. Verify you're using the correct secret (the one returned when creating the endpoint)
2. Ensure you're computing the signature on the raw JSON body
3. Use timing-safe comparison functions

### Delivery Delays

Webhooks are delivered in near real-time but may be delayed if:

* Your endpoint is slow to respond (>30 seconds causes timeout and retry)
* Previous deliveries to your endpoint failed (retries queue up)

***

## Best Practices

1. **Respond quickly** - Return a 200 response immediately, process data asynchronously
2. **Verify signatures** - Always verify the X-Hook-Signature header
3. **Handle duplicates** - Use the `_id` field to deduplicate in rare cases of redelivery
4. **Monitor stats** - Check failed\_deliveries regularly to catch issues early
5. **Use descriptive names** - Set meaningful descriptions to identify endpoints

<br />