🪝Webhooks

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

NOTE: V3 is currently in the beta phase and is subject to change.

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

Body

application/json

callbackUrl*string

The URL to send the webhook to

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

enabledEvents*array of enum

The events that are enabled for this webhook

secretstring

A secret to sign the webhook with

Example: "supersecret"

Response

201401

Webhook created

Body

application/json

id*string

The ID of the webhook subscription

Example: "60f8c3b3c4e5c3001f5b5c3e"

callbackUrl*string

The URL to ping when the event occurs

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

enabledEvents*array of string

The events that are enabled for this webhook

createdAt*string (date-time)

The creation date of the webhook subscription

Example: "2021-07-22T15:00:35.000Z"

updatedAt*string (date-time)

The last update date of the webhook subscription

Example: "2021-07-22T15:00:35.000Z"

Request

JavaScriptCurlPython

const response = await fetch('/api/v3/webhooks', {
    method: 'POST',
    headers: {
      "x-api-token": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "callbackUrl": "https://example.com/webhook",
      "enabledEvents": [
        "pud:status_update",
        "pud:price_update"
      ]
    }),
});
const data = await response.json();

Response

201401

{
  "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/api/v3/webhooks/{id}

Path parameters

id*string

Webhook id

Header parameters

Response

200401

Webhook found

Body

application/json

id*string

The ID of the webhook subscription

Example: "60f8c3b3c4e5c3001f5b5c3e"

callbackUrl*string

The URL to ping when the event occurs

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

enabledEvents*array of string

The events that are enabled for this webhook

createdAt*string (date-time)

The creation date of the webhook subscription

Example: "2021-07-22T15:00:35.000Z"

updatedAt*string (date-time)

The last update date of the webhook subscription

Example: "2021-07-22T15:00:35.000Z"

Request

JavaScriptCurlPython

const response = await fetch('/api/v3/webhooks/{id}', {
    method: 'GET',
    headers: {
      "x-api-token": "text"
    },
});
const data = await response.json();

Response

200401

{
  "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/api/v3/webhooks

Header parameters

Response

200401

Webhooks found

Body

application/json

id*string

The ID of the webhook subscription

Example: "60f8c3b3c4e5c3001f5b5c3e"

callbackUrl*string

The URL to ping when the event occurs

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

enabledEvents*array of string

The events that are enabled for this webhook

createdAt*string (date-time)

The creation date of the webhook subscription

Example: "2021-07-22T15:00:35.000Z"

updatedAt*string (date-time)

The last update date of the webhook subscription

Example: "2021-07-22T15:00:35.000Z"

Request

JavaScriptCurlPython

const response = await fetch('/api/v3/webhooks', {
    method: 'GET',
    headers: {
      "x-api-token": "text"
    },
});
const data = await response.json();

Response

200401

[
  {
    "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/api/v3/webhooks/{id}

Path parameters

id*string

Webhook id

Header parameters

Body

application/json

callbackUrlstring

The URL to send the webhook to

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

enabledEventsarray of enum

The events that are enabled for this webhook

Response

200401

Webhook updated

Body

application/json

id*string

The ID of the webhook subscription

Example: "60f8c3b3c4e5c3001f5b5c3e"

callbackUrl*string

The URL to ping when the event occurs

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

enabledEvents*array of string

The events that are enabled for this webhook

createdAt*string (date-time)

The creation date of the webhook subscription

Example: "2021-07-22T15:00:35.000Z"

updatedAt*string (date-time)

The last update date of the webhook subscription

Example: "2021-07-22T15:00:35.000Z"

Request

JavaScriptCurlPython

const response = await fetch('/api/v3/webhooks/{id}', {
    method: 'PATCH',
    headers: {
      "x-api-token": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200401

{
  "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/api/v3/webhooks/{id}

Path parameters

id*string

Webhook id

Header parameters

Response

200401

Webhook deleted

Request

JavaScriptCurlPython

const response = await fetch('/api/v3/webhooks/{id}', {
    method: 'DELETE',
    headers: {
      "x-api-token": "text"
    },
});
const data = await response.json();

Response

401

{
  "message": "Unauthorized. Please provide valid credentials"
}

---

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: 'delegated',
        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.