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

401

Unauthorized

application/json

post

HTTPcURLJavaScriptPython

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

401

Unauthorized

application/json

get

HTTPcURLJavaScriptPython

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

401

Unauthorized

application/json

get

HTTPcURLJavaScriptPython

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

401

Unauthorized

application/json

patch

HTTPcURLJavaScriptPython

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

401

Unauthorized

application/json

delete

HTTPcURLJavaScriptPython

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.