Webhooks

Webhooks provide a powerful way to receive real-time notifications of events in your system.

Create a test account to get started.

Test Account Setup

Overview

When certain events occur, our API will send an HTTP POST request to the specified URL, delivering a payload with event details. This enables you to automate reactions or synchronize data without the need for polling.

Events

Here are the currently supported events you can subscribe to:

Event
Description

pud:status_update

Status changes on a PUD

pud:price_update

Price changes on a PUD

Create a webhook

post
Header parameters
x-api-tokenstringRequired

Company API token

Body
callbackUrlstringRequired

The URL to send the webhook to

Example: https://example.com/webhook
secretstringOptional

A secret to sign the webhook with

Example: supersecret
Responses
201
Webhook created
application/json
post
POST /api/v3/webhooks HTTP/1.1
Host: 
x-api-token: text
Content-Type: application/json
Accept: */*
Content-Length: 125

{
  "callbackUrl": "https://example.com/webhook",
  "enabledEvents": [
    "pud:status_update",
    "pud:price_update"
  ],
  "secret": "supersecret"
}
{
  "id": "60f8c3b3c4e5c3001f5b5c3e",
  "callbackUrl": "https://example.com/webhook",
  "enabledEvents": [
    "pud:status_update",
    "pud:price_update"
  ],
  "createdAt": "2021-07-22T15:00:35.000Z",
  "updatedAt": "2021-07-22T15:00:35.000Z"
}

Get a webhook

get
Path parameters
idstringRequired

Webhook id

Header parameters
x-api-tokenstringRequired

Company API token

Responses
200
Webhook found
application/json
get
GET /api/v3/webhooks/{id} HTTP/1.1
Host: 
x-api-token: text
Accept: */*

{
  "id": "60f8c3b3c4e5c3001f5b5c3e",
  "callbackUrl": "https://example.com/webhook",
  "enabledEvents": [
    "pud:status_update",
    "pud:price_update"
  ],
  "createdAt": "2021-07-22T15:00:35.000Z",
  "updatedAt": "2021-07-22T15:00:35.000Z"
}

Get all webhooks

get
Header parameters
x-api-tokenstringRequired

Company API token

Responses
200
Webhooks found
application/json
get
GET /api/v3/webhooks HTTP/1.1
Host: 
x-api-token: text
Accept: */*

[
  {
    "id": "60f8c3b3c4e5c3001f5b5c3e",
    "callbackUrl": "https://example.com/webhook",
    "enabledEvents": [
      "pud:status_update",
      "pud:price_update"
    ],
    "createdAt": "2021-07-22T15:00:35.000Z",
    "updatedAt": "2021-07-22T15:00:35.000Z"
  }
]

Update a webhook

patch
Path parameters
idstringRequired

Webhook id

Header parameters
x-api-tokenstringRequired

Company API token

Body
callbackUrlstringOptional

The URL to send the webhook to

Example: https://example.com/webhook
Responses
200
Webhook updated
application/json
patch
PATCH /api/v3/webhooks/{id} HTTP/1.1
Host: 
x-api-token: text
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "callbackUrl": "https://example.com/webhook",
  "enabledEvents": [
    "pud:status_update",
    "pud:price_update"
  ]
}
{
  "id": "60f8c3b3c4e5c3001f5b5c3e",
  "callbackUrl": "https://example.com/webhook",
  "enabledEvents": [
    "pud:status_update",
    "pud:price_update"
  ],
  "createdAt": "2021-07-22T15:00:35.000Z",
  "updatedAt": "2021-07-22T15:00:35.000Z"
}

Delete a webhook

delete
Path parameters
idstringRequired

Webhook id

Header parameters
x-api-tokenstringRequired

Company API token

Responses
200
Webhook deleted
delete
DELETE /api/v3/webhooks/{id} HTTP/1.1
Host: 
x-api-token: text
Accept: */*

No content

Webhook payloads

When an event occurs, we'll send a POST request to the callback_url. The data object will depend on the eventType. See the payload data examples below.

NOTE: If a secret was provided when creating a webhook, we'll use it to create a hash signature that's sent in the X-Hub-Signature-256 header.

Validating webhook deliveries

Headers

Name
Value

X-Hub-Signature-256

sha256=<signature>

Body

Name
Type
Description

id

string

Id of event

eventType

string

Type of event

timestamp

Date

Date and time of event

data

object

Payload data (see below)

pud:status_update
{
...
data: {
        pudId: 'f0bdb31f-b243-4f5f-90d7-440f1897d681',
        referenceNumber: "ref-number", // null if no referenceNumber
        prevStatus: 'pre_trip_inspection',
        newStatus: 'in_progress'
    }
}
pud:price_update
{
...
data: {
        pudId: 'f0bdb31f-b243-4f5f-90d7-440f1897d681',
        referenceNumber: "ref-number", // null if no referenceNumber
        prevPrice: 429,
        newPrice: 529
    }
}

Validating webhook deliveries

If you provided a secret when creating a webhook, Gire will use it, along with the payload, to create a hash signature that is sent in the X-Hub-Signature-256 header. You can use this to verify the integrity and authenticity of the webhook payload.

Example validation

  1. Receive payload and signature: Your server gets the payload and the X-Hub-Signature-256 header.

  2. Generate signature: Use HMAC SHA-256 with the secret and the raw payload to compute a hash.

  3. Compare signature: Compare your computed hash with the signature received in the header. If they match, the payload is verified and authentic.

Last updated