Webhooks Overview

Webhooks allow you to receive real-time HTTP POST notifications when events occur in your Hydra account.

How It Works

1. Configure an endpoint - Add your webhook URL in Settings > Webhooks
2. Select events - Choose which events you want to receive
3. Receive notifications - We'll send POST requests to your URL when events occur
4. Verify signatures - Use the signing secret to verify requests are from Hydra

Supported Events

Service Jobs

• service_job.created - A new job was created
• service_job.status_changed - A job's status changed
• service_job.completed - A job was marked complete
• service_job.cancelled - A job was cancelled

Bookings

• booking.created - A new booking was created
• booking.confirmed - A booking was confirmed
• booking.cancelled - A booking was cancelled
• booking.completed - A booking was completed

Parts

• part.created - A new part was created
• part.updated - A part was updated
• part.deleted - A part was deleted
• part.stock_updated - Part stock quantity changed

Company

• company.member_added - A team member was added
• company.member_removed - A team member was removed

Webhook Payload Format

All webhooks are sent as POST requests with JSON body:

{
    "event": "service_job.created",
    "timestamp": "2024-01-15T08:30:00Z",
    "data": {
        "id": 1,
        "job_number": "JOB-2024-0001",
        ...
    }
}

Webhook Headers

Each request includes these headers:

Verifying Signatures

To verify a webhook is from Hydra:

$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'your_webhook_secret';

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if (hash_equals($expected, $signature)) {
    // Valid webhook
}

Retry Policy

If your endpoint returns a non-2xx status code, we'll retry:

• 1st retry: 1 minute later
• 2nd retry: 5 minutes later
• 3rd retry: 30 minutes later
• 4th retry: 2 hours later
• 5th retry: 12 hours later

After 5 failed attempts, the delivery is marked as failed. After 10 consecutive failures across multiple deliveries, your endpoint will be automatically disabled.

Best Practices

1. Respond quickly - Return a 200 status within 30 seconds
2. Process asynchronously - Queue the webhook for processing
3. Verify signatures - Always verify the signature before processing
4. Handle duplicates - Webhooks may be delivered more than once