🪝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

/api/v3/webhooks

Header parameters

x-api-tokenstringrequired

Company API token

Body

callbackUrlstringrequired

The URL to send the webhook to

Example: https://example.com/webhook

enabledEventsstring · enum[]required

The events that are enabled for this webhook

Example: ["pud:status_update","pud:price_update"]

secretstring

A secret to sign the webhook with

Example: supersecret

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v3/webhooks' \
  --header 'x-api-token: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "callbackUrl": "https://example.com/webhook",
    "enabledEvents": [
      "pud:status_update",
      "pud:price_update"
    ],
    "secret": "supersecret"
  }'

201

401

201

{
  "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"
}

Webhook created

Get a webhook

get

/api/v3/webhooks/{id}

Path parameters

idstringrequired

Webhook id

Header parameters

x-api-tokenstringrequired

Company API token

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v3/webhooks/{id}' \
  --header 'x-api-token: text'

200

401

200

{
  "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"
}

Webhook found

Get all webhooks

get

/api/v3/webhooks

Header parameters

x-api-tokenstringrequired

Company API token

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v3/webhooks' \
  --header 'x-api-token: text'

200

401

200

[
  {
    "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"
  }
]

Webhooks found

Update a webhook

patch

/api/v3/webhooks/{id}

Path parameters

idstringrequired

Webhook id

Header parameters

x-api-tokenstringrequired

Company API token

Body

callbackUrlstring

The URL to send the webhook to

Example: https://example.com/webhook

enabledEventsstring · enum[]

The events that are enabled for this webhook

Example: ["pud:status_update","pud:price_update"]

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url '/api/v3/webhooks/{id}' \
  --header 'x-api-token: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "callbackUrl": "https://example.com/webhook",
    "enabledEvents": [
      "pud:status_update",
      "pud:price_update"
    ]
  }'

200

401

200

{
  "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"
}

Webhook updated

Delete a webhook

delete

/api/v3/webhooks/{id}

Path parameters

idstringrequired

Webhook id

Header parameters

x-api-tokenstringrequired

Company API token

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '/api/v3/webhooks/{id}' \
  --header 'x-api-token: text'

200

401

200

No body

Webhook deleted

---

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',
        prevStatus: 'pre_trip_inspection',
        newStatus: 'in_progress'
    }
}

pud:price_update

{
...
data: {
        pudId: 'f0bdb31f-b243-4f5f-90d7-440f1897d681',
        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.