Webhooks

Overview

Webhooks notify your system in real time when something happens to an appointment in Conduit: it's booked, confirmed, checked in, rescheduled, cancelled, and so on. This is useful for keeping a TMS, WMS, ERP or other system in sync with appointment status, check in and check out times, dock assignments and other appointment data.

Each webhook is a small JSON notification sent over HTTPS. It tells you which appointment changed and what kind of change it was. It does not include the appointment's data. To get the data, call the Conduit API when you receive the event.

Custom webhooks

This guide describes Conduit's default webhooks. Conduit can also support custom adapters that send webhooks in a different format, such as a payload that includes appointment data, a specific schema, or a different authentication method. If your system needs something different, contact us at [email protected] to discuss.

How it works

1. Something happens to an appointment, such as a driver checking in.
2. Conduit sends a POST request to your endpoint with the event. The event contains the appointment's ID, not the appointment itself.
3. Your endpoint verifies the signature, records the event and returns a 200.
4. Your system fetches the appointment from Get FacilityAppointment using the facility_appointment ID in the event, and updates its own records from the response.

Payload

{
  "id": "6f1c2a7e-9b3d-4c1f-8e2a-5d7b9c0e1f23",
  "facility": "2aae24c7-438d-473f-aba8-7793b7efdec3",
  "facility_appointment": "0bc8eae3-2e91-43ef-bd4a-164c76618942",
  "created_at": "2025-01-08T15:04:05.123456+00:00",
  "event_category": "APPOINTMENT_CHECK_IN"
}

Event categories

Conduit sets which event categories your endpoint receives when we set up your webhooks. Let us know if you only want some of them.

One action can produce more than one event. For example, editing an appointment's dock and its scheduled time together sends both APPOINTMENT_INFO_UPDATED and APPOINTMENT_FACILITY_RESCHEDULED.

Setup

1. Create an HTTPS endpoint that accepts POST requests with a JSON body and returns a 200.
2. Test the endpoint with the sample payload above.
3. Deploy the endpoint so that it is publicly accessible.
4. Contact us at [email protected] with your endpoint URL and the event categories you want. We'll send you your signing secret.

Receiving events

We recommend handling each event like this:

1. Verify the signature. Reject the request if it doesn't match.
2. If you've already processed an event with the same id, return 200 and stop.
3. Store the event or put it on a queue, then return 200.
4. In the background, fetch the appointment and update your system.

Retries and ordering

If your endpoint doesn't return a 200, Conduit retries the event a few times over the next several minutes, then keeps retrying periodically for up to 24 hours. After that the event is dropped.

Endpoints that fail consistently for 7 days will be turned off until we can get in contact with you.

Because of retries:

• You may receive the same event more than once. Use id to ignore duplicates.
• Events may arrive late or out of order. Use created_at for when the event happened, and fetch the appointment for its current state.

Verification

Each webhook includes a Conduit-Signature header so you can confirm it came from Conduit. The signature is an HMAC-SHA256 of the request, signed with your signing secret.

Conduit-Signature: t=1683607883;v0=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

How to verify

1. Read the timestamp and signature from the header. Split the header on ;, then split each part on the first =. t is the Unix timestamp, in seconds, when the request was signed. v0 is the signature.
2. Build the signed payload. Join the timestamp and the raw request body: {t}{raw body}, with nothing in between. Use the body exactly as received. Parsing the JSON and serializing it again can change spacing and break the signature.
3. Compute the expected signature. Calculate an HMAC-SHA256 of the signed payload, using your signing secret as the key, and hex-encode it.
4. Compare the signatures. Compare the expected signature with v0 using a constant-time comparison. If they match, check that t is within your tolerance of the current time, for example 5 minutes, to protect against replayed requests.

Each retry is signed again with a new timestamp, so retried events still pass a timestamp check.

Examples

import hashlib
import hmac
import time


def is_valid_conduit_signature(raw_body: bytes, signature_header: str, signing_secret: str, tolerance_seconds: int = 300) -> bool:
    parts = dict(part.split("=", 1) for part in signature_header.split(";"))
    timestamp = parts["t"]
    signature = parts["v0"]

    signed_payload = timestamp.encode() + raw_body
    expected_signature = hmac.new(signing_secret.encode(), signed_payload, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected_signature, signature):
        return False

    return abs(time.time() - int(timestamp)) <= tolerance_seconds

const crypto = require("crypto");

function isValidConduitSignature(rawBody, signatureHeader, signingSecret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    signatureHeader.split(";").map((part) => {
      const separatorIndex = part.indexOf("=");
      return [part.slice(0, separatorIndex), part.slice(separatorIndex + 1)];
    })
  );

  const expectedSignature = crypto
    .createHmac("sha256", signingSecret)
    .update(parts.t + rawBody)
    .digest("hex");

  const expected = Buffer.from(expectedSignature);
  const received = Buffer.from(parts.v0 ?? "");
  if (expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) {
    return false;
  }

  return Math.abs(Date.now() / 1000 - Number(parts.t)) <= toleranceSeconds;
}

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HashMap;
import java.util.HexFormat;
import java.util.Map;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class ConduitWebhookVerifier {
    public static boolean isValidConduitSignature(byte[] rawBody, String signatureHeader, String signingSecret, long toleranceSeconds) throws Exception {
        Map<String, String> parts = new HashMap<>();
        for (String part : signatureHeader.split(";")) {
            String[] keyValue = part.split("=", 2);
            if (keyValue.length == 2) {
                parts.put(keyValue[0], keyValue[1]);
            }
        }
        String timestamp = parts.get("t");
        String signature = parts.get("v0");
        if (timestamp == null || signature == null) {
            return false;
        }

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(signingSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update(timestamp.getBytes(StandardCharsets.UTF_8));
        String expectedSignature = HexFormat.of().formatHex(mac.doFinal(rawBody));

        if (!MessageDigest.isEqual(expectedSignature.getBytes(StandardCharsets.UTF_8), signature.getBytes(StandardCharsets.UTF_8))) {
            return false;
        }

        return Math.abs(Instant.now().getEpochSecond() - Long.parseLong(timestamp)) <= toleranceSeconds;
    }
}

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

public static class ConduitWebhookVerifier
{
    public static bool IsValidConduitSignature(byte[] rawBody, string signatureHeader, string signingSecret, long toleranceSeconds = 300)
    {
        var parts = new Dictionary<string, string>();
        foreach (var part in signatureHeader.Split(';'))
        {
            var keyValue = part.Split('=', 2);
            if (keyValue.Length == 2)
            {
                parts[keyValue[0]] = keyValue[1];
            }
        }
        if (!parts.TryGetValue("t", out var timestamp) || !parts.TryGetValue("v0", out var signature))
        {
            return false;
        }

        var signedPayload = Encoding.UTF8.GetBytes(timestamp).Concat(rawBody).ToArray();
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signingSecret));
        var expectedSignature = Convert.ToHexString(hmac.ComputeHash(signedPayload)).ToLowerInvariant();

        if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expectedSignature), Encoding.UTF8.GetBytes(signature)))
        {
            return false;
        }

        return long.TryParse(timestamp, out var timestampSeconds)
            && Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestampSeconds) <= toleranceSeconds;
    }
}