Webhooks

Webhooks will send a HTTP request to a URL when an event happens in the Client Dashboard. You will be given a webhook secret key to verify requests.

Webhook Headers

For security we send some extra headers so you can verify the events.

POST https://example.com/webhook

Content-Type: application/json,
User-Agent: clients.icaal.co.uk/1.0,
X-ICAAL-Signature: 594a6ca9d134d8664977d98f43f1f01eaa785600,
X-ICAAL-Account-Key: API-KEY

Verifying Requests

The signature can be found in the X-ICAAL-Signature header. This signature is a sha1 hash from the body of the webhook signed with your webhook secret key. If they don't match you shouldn't accept the request.

Here's an example of how you can verify incoming webhooks:

PHP

$webhook_secret = 'WEBHOOK_SECRET';
$raw_post_data = file_get_contents('php://input');
$header_signature = $headers['X-ICAAL-Signature'];

$expected_signature = hash_hmac('sha1', $raw_post_data, $webhook_secret);

if (! hash_equals($header_signature, $expected_signature)) {
    // Signature not verified
    exit;
}

Failed Webhooks

If the webhook fails to receive a 2xx response code it will attempt to retry after the following intervals:

1. 60 seconds

2. 5 minutes

3. 15 minutes

4. 30 minutes

5. 1 hour

Webhook Types

Lead Created

When a lead is created it will trigger this webhook. The data sent will depend on the type of lead. There are some examples below

Quote

{
  "data": {
    "id": 1,
    "reference": "92ccb3f8-358f-4ffc-be49-683f5a0b3a65",
    "name": "Casement Window Lead",
    "value": 0,
    "description": null,
    "postcode": "SO14 2AL",
    "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_15_0) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/89.0.4389.82 Safari\/537.36",
    "ip": "192.168.10.1",
    "referrer": "Direct",
    "referrer_url": null,
    "device_type": "desktop",
    "device_name": "Apple Macintosh",
    "browser": "Chrome",
    "browser_version": "89.0.4389.82",
    "os": "OS X",
    "os_version": "10.15.0",
    "status": "open",
    "type": "quote",
    "test": 1,
    "created_at": "2021-01-01T12:00:00.000000Z",
    "updated_at": "2021-01-01T12:00:00.000000Z",
    "customer": {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
      "name": "John Doe",
      "company_name": null,
      "email": "[email protected]",
      "phone": "023 8033 2675",
      "phone_link": "tel:[phone]",
      "mobile": null,
      "mobile_link": null,
      "address_1": null,
      "address_2": null,
      "city": null,
      "county": null,
      "postcode": "SO14 2AL",
      "avatar_url": null,
      "created_at": "2021-01-01T12:00:00.000000Z"
    },
    "quotes": [
      {
        "id": 1,
        "lead_id": 1,
        "status": "complete",
        "created_at": "2021-01-01T12:00:00.000000Z",
        "updated_at": "2021-01-01T12:00:00.000000Z",
        "items": [
          {
            "id": 1,
            "quote_id": 1,
            "product_style_id": 1,
            "name": "Casement Window",
            "price": 52500,
            "cost": null,
            "margin": null,
            "tax": null,
            "minimum": null,
            "maximum": null,
            "format": "range",
            "hidden": 1,
            "status": "active",
            "created_at": "2021-01-01T12:00:00.000000Z",
            "updated_at": "2021-01-01T12:00:00.000000Z",
            "image": {
              "id": 1,
              "name": null,
              "file_name": "S1.svg",
              "file_size": 54445,
              "content_type": "image/svg+xml",
              "alt": null,
              "public": 1,
              "processed": 0,
              "created_at": "2021-01-01T12:00:00.000000Z",
              "updated_at": "2021-01-01T12:00:00.000000Z",
              "url": "https://assets.clients.icaal.co.uk/storage/images/1/original/S1.svg"
            },
            "options": {
              "width": 800,
              "height": 800,
              "external_frame_colour": "white",
              "internal_frame_colour": "white",
              "glass": "clear",
              "frame_material": "upvc"
            }
          }
        ]
      }
    ]
  }
}