Webhooks

Overview

Webhooks allow you to receive real-time updates of events from Conduit. Our Webhooks use HTTPS to send notifications to your app as a JSON payload. You can then use these notifications to execute actions in your systems. This is particularly useful if you're storing appointment info, check in and check out times, dock assignments or other data in other systems such a Transportation Management System or Warehouse Management System.

Instead of including the appointment information in the webhook payload body, the recieving system for these webhook events should use the provided appointment ID and facility ID to pull the appointment information from our APIs (if the system needs more information about the API) about that appointment to avoid any race conditions.

Payload

The JSON payload for a Webhook is shown below:

{
  "id": <uuid>
  "facility": <uuid>
  "facility_appointment": <uuid>
  "created_at": <string>
  "event_category" <string>
}

Event Categories

    APPOINTMENT_REQUESTED
    APPOINTMENT_REQUEST_DECLINED
    APPOINTMENT_CONFIRMED
    APPOINTMENT_CREATED
    WORK_IN_CREATED
    APPOINTMENT_CANCELLED
    APPOINTMENT_CARRIER_CANCELLED
    APPOINTMENT_LOAD_REJECTED
    APPOINTMENT_CHECKED_IN
    DRIVER_CHECKED_IN
    APPOINTMENT_CHECKED_OUT
    APPOINTMENT_INFO_UPDATED
    APPOINTMENT_ETA_UPDATED
    APPOINTMENT_AUTO_CANCELLED
    ETA_UPDATE_REQUESTED
    APPOINTMENT_FACILITY_RESCHEDULED
    APPOINTMENT_CARRIER_RESCHEDULED
    APPOINTMENT_ATTACHMENT_CREATED
    APPOINTMENT_ATTACHMENT_DELETED

Setup

To get setup with Webhooks, take the following steps:

1. Create an HTTP webhook endpoint that will receive and parse our JSON payloads and return a 200.
2. Test the endpoint with a sample payload.
3. Deploy the endpoint such that it is publically accessible.
4. Contact us at [email protected] to share your endpoint url and get setup with Conduit Webhooks.

Verification

To verify that a webhook is coming from Conduit, we include a signature in the header called Conduit-Signature that is an HMAC-SHA256 hash of the raw request body. We will share your personal signing key with you when you contact us to setup Webhooks.

Here's a sample header

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

How to Verify

1. Extract the timestamp and signatures from the header.

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v0 corresponds to the signature.

2. Create the signed_payload string

The signed_payload string is created by concatenating:

• The timestamp (as a string)
• The actual JSON payload (that is, the request body)

3. Create the expected signature

Compute an HMAC with the SHA256 hash function. Use your signing secret as the key, and use the signed_payload string as the message.

4. Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.