Overview

Webhooks allow you to receive real-time notifications when data changes in the API. When an event occurs (such as a project being updated), the API will send a POST request to your configured webhook URL with the event data.

Webhook Events

Available Events

project.created - When a new project is created
project.updated - When an existing project is updated
project.deleted - When a project is deleted
floorplan.created - When a new floorplan is added
floorplan.updated - When a floorplan is updated
floorplan.deleted - When a floorplan is deleted
document.created - When a new document is added
document.updated - When a document is updated

Configure Your Endpoint

Set up an endpoint on your server to receive webhook requests:

<?php
// webhook-endpoint.php

// Get the raw POST body
$receivedPayloadJson = file_get_contents('php://input');

// Get the signature from headers
$receivedSignature = $_SERVER['HTTP_SIGNATURE'] ?? '';

// Your webhook secret (configured when creating the webhook)
$secret = 'your-webhook-secret';

// Calculate the expected signature
$calculatedSignature = hash_hmac('sha256', $receivedPayloadJson, $secret);

// Verify the signature
if (hash_equals($calculatedSignature, $receivedSignature)) {
    // Webhook is valid
    $payload = json_decode($receivedPayloadJson, true);
    
    // Process the webhook data
    $event = $payload['event'];
    $data = $payload['data'];
    
    // Handle different events
    switch ($event) {
        case 'project.created':
            handleProjectCreated($data);
            break;
        case 'project.updated':
            handleProjectUpdated($data);
            break;
        case 'floorplan.created':
            handleFloorplanCreated($data);
            break;
        case 'floorplan.updated':
            handleFloorplanUpdated($data);
            break;
        case 'document.created':
            handleDocumentCreated($data);
            break;
        // ... handle other events
    }
    
    // Return success response
    http_response_code(200);
    echo json_encode(['status' => 'success']);
} else {
    // Invalid signature
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
}

function handleProjectCreated($data) {
    // Handle project created event
    // $data contains the project information
    error_log("Project created: " . $data['id']);
}

function handleProjectUpdated($data) {
    // Handle project updated event
    // $data contains the updated project information
    error_log("Project updated: " . $data['id']);
}

function handleFloorplanCreated($data) {
    // Handle floorplan created event
    // $data contains the floorplan information
    error_log("Floorplan created: " . $data['id']);
}

function handleFloorplanUpdated($data) {
    // Handle floorplan updated event
    // $data contains the updated floorplan information
    error_log("Floorplan updated: " . $data['id']);
}

function handleDocumentCreated($data) {
    // Handle document created event
    // $data contains the document information
    error_log("Document created: " . $data['id']);
}
?>

Webhook Payload Format

Request Headers

Content-Type: application/json
Signature: {calculated_signature}

Payload Structure

{
  "event": "project.updated",
  "data": {
    "id": 123,
    "name": "Updated Project Name",
    "status": "selling",
    "updated_at": "2025-08-25T10:30:00Z"
  },
  "timestamp": "2025-08-25T10:30:00Z",
  "delivery_id": "webhook_delivery_abc123"
}

Security

Signature Verification

The webhook signature is calculated using HMAC-SHA256:

$signature = hash_hmac('sha256', $payload, $secret);

Important: Always verify the signature before processing webhook data to ensure the request came from the Red Bricks API.

Best Practices

Use HTTPS - Always use HTTPS for your webhook endpoints
Verify Signatures - Always verify the webhook signature
Handle Duplicates - Webhooks may be retried, so handle duplicate deliveries
Return 200 - Return HTTP 200 to acknowledge receipt
Process Asynchronously - Process webhook data asynchronously when possible

Last updated: September 2025