Webhook Documentation

Learn how to receive real-time notifications about events in your HatchBeacon account

Overview

Webhooks allow you to receive HTTP POST notifications whenever specific events occur in your account. This enables you to build integrations that react to changes in real-time.

Creating a Webhook

1. Navigate to Settings → Integrations → Webhooks
2. Click "Add Webhook"
3. Enter a name and your endpoint URL
4. Select the events you want to subscribe to
5. Save your webhook and copy the signing secret

Webhook Payload

All webhook requests are sent as HTTP POST with a JSON payload:

{
  "event": "job_application_created",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "data": {
    "log": {
      "action": "create_application",
      "resourceType": "job_application",
      "resourceId": "507f1f77bcf86cd799439011",
      "userId": "507f191e810c19729de860ea",
      "userName": "John Doe",
      "userEmail": "john@example.com",
      "timestamp": "2024-01-20T10:30:00.000Z"
    },
    "details": {
      "method": "POST",
      "path": "/job-applications",
      "candidateName": "Jane Smith",
      "jobTitle": "Senior Developer"
    }
  }
}

Available Events

Verifying Webhook Signatures

Each webhook request includes an X-Webhook-Signature header containing an HMAC SHA-256 signature. You should verify this signature to ensure the request came from HatchBeacon.

Node.js Example

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js middleware example
app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  const { event, data } = req.body;
  console.log(`Received event: ${event}`);
  
  res.status(200).send('OK');
});

Python Example

import hmac
import hashlib
import json

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        json.dumps(payload).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

# Flask example
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    secret = os.environ.get('WEBHOOK_SECRET')
    
    if not verify_webhook_signature(request.json, signature, secret):
        return 'Invalid signature', 401
    
    # Process the webhook
    event = request.json['event']
    data = request.json['data']
    print(f'Received event: {event}')
    
    return 'OK', 200

Best Practices

Retry Behavior

If your endpoint returns a non-2xx status code or times out, we'll retry the webhook with exponential backoff: