> For the complete documentation index, see [llms.txt](https://giremobility.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://giremobility.gitbook.io/api/v3/webhooks.md).

# Webhooks

{% hint style="info" %}
**Create a test account to get started.**

[Test Account Setup](/api/v3/test-account-setup.md)
{% endhint %}

### 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:create         | PUD is created          |
| pud:status\_update | Status changes on a PUD |
| pud:price\_update  | Price changes on a PUD  |

## POST /api/v3/webhooks

> Create a webhook

```json
{"openapi":"3.0.0","info":{"title":"Gire Public API","version":"3.0"},"paths":{"/api/v3/webhooks":{"post":{"operationId":"WebhookController_create","parameters":[{"name":"x-api-token","in":"header","description":"Company API token","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookDto"}}}},"responses":{"201":{"description":"Webhook created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}}},"summary":"Create a webhook","tags":["[API] Webhooks"]}}},"components":{"schemas":{"CreateWebhookDto":{"type":"object","properties":{"callbackUrl":{"type":"string","description":"The URL to send the webhook to"},"enabledEvents":{"type":"array","description":"The events that are enabled for this webhook","items":{"type":"string","enum":["pud:create","pud:status_update","pud:price_update"]}},"secret":{"type":"string","description":"A secret to sign the webhook with"}},"required":["callbackUrl","enabledEvents"]},"WebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the webhook subscription"},"callbackUrl":{"type":"string","description":"The URL to ping when the event occurs"},"enabledEvents":{"description":"The events that are enabled for this webhook","type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string","description":"The creation date of the webhook subscription"},"updatedAt":{"format":"date-time","type":"string","description":"The last update date of the webhook subscription"}},"required":["id","callbackUrl","enabledEvents","createdAt","updatedAt"]},"UnauthorizedResponse":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}}}}
```

## GET /api/v3/webhooks/{id}

> Get a webhook

```json
{"openapi":"3.0.0","info":{"title":"Gire Public API","version":"3.0"},"paths":{"/api/v3/webhooks/{id}":{"get":{"operationId":"WebhookController_get","parameters":[{"name":"x-api-token","in":"header","description":"Company API token","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Webhook id","schema":{}}],"responses":{"200":{"description":"Webhook found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}}},"summary":"Get a webhook","tags":["[API] Webhooks"]}}},"components":{"schemas":{"WebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the webhook subscription"},"callbackUrl":{"type":"string","description":"The URL to ping when the event occurs"},"enabledEvents":{"description":"The events that are enabled for this webhook","type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string","description":"The creation date of the webhook subscription"},"updatedAt":{"format":"date-time","type":"string","description":"The last update date of the webhook subscription"}},"required":["id","callbackUrl","enabledEvents","createdAt","updatedAt"]},"UnauthorizedResponse":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}}}}
```

## GET /api/v3/webhooks

> Get all webhooks

```json
{"openapi":"3.0.0","info":{"title":"Gire Public API","version":"3.0"},"paths":{"/api/v3/webhooks":{"get":{"operationId":"WebhookController_getAll","parameters":[{"name":"x-api-token","in":"header","description":"Company API token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Webhooks found","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookResponse"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}}},"summary":"Get all webhooks","tags":["[API] Webhooks"]}}},"components":{"schemas":{"WebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the webhook subscription"},"callbackUrl":{"type":"string","description":"The URL to ping when the event occurs"},"enabledEvents":{"description":"The events that are enabled for this webhook","type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string","description":"The creation date of the webhook subscription"},"updatedAt":{"format":"date-time","type":"string","description":"The last update date of the webhook subscription"}},"required":["id","callbackUrl","enabledEvents","createdAt","updatedAt"]},"UnauthorizedResponse":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}}}}
```

## PATCH /api/v3/webhooks/{id}

> Update a webhook

```json
{"openapi":"3.0.0","info":{"title":"Gire Public API","version":"3.0"},"paths":{"/api/v3/webhooks/{id}":{"patch":{"operationId":"WebhookController_update","parameters":[{"name":"x-api-token","in":"header","description":"Company API token","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Webhook id","schema":{}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookDto"}}}},"responses":{"200":{"description":"Webhook updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}}},"summary":"Update a webhook","tags":["[API] Webhooks"]}}},"components":{"schemas":{"UpdateWebhookDto":{"type":"object","properties":{"callbackUrl":{"type":"string","description":"The URL to send the webhook to"},"enabledEvents":{"type":"array","description":"The events that are enabled for this webhook","items":{"type":"string","enum":["pud:create","pud:status_update","pud:price_update"]}}}},"WebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the webhook subscription"},"callbackUrl":{"type":"string","description":"The URL to ping when the event occurs"},"enabledEvents":{"description":"The events that are enabled for this webhook","type":"array","items":{"type":"string"}},"createdAt":{"format":"date-time","type":"string","description":"The creation date of the webhook subscription"},"updatedAt":{"format":"date-time","type":"string","description":"The last update date of the webhook subscription"}},"required":["id","callbackUrl","enabledEvents","createdAt","updatedAt"]},"UnauthorizedResponse":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}}}}
```

## DELETE /api/v3/webhooks/{id}

> Delete a webhook

```json
{"openapi":"3.0.0","info":{"title":"Gire Public API","version":"3.0"},"paths":{"/api/v3/webhooks/{id}":{"delete":{"operationId":"WebhookController_delete","parameters":[{"name":"x-api-token","in":"header","description":"Company API token","required":true,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Webhook id","schema":{}}],"responses":{"200":{"description":"Webhook deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}}},"summary":"Delete a webhook","tags":["[API] Webhooks"]}}},"components":{"schemas":{"UnauthorizedResponse":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}}}}
```

***

## 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.

{% hint style="info" %}
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](#validating-webhook-deliveries "mention")
{% endhint %}

**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) |

<details>

<summary>pud:status_update</summary>

```
{
...
data: {
        pudId: 'f0bdb31f-b243-4f5f-90d7-440f1897d681',
        referenceNumber: "ref-number", // null if no referenceNumber
        prevStatus: 'pre_trip_inspection',
        newStatus: 'in_progress'
    }
}
```

</details>

<details>

<summary>pud:price_update</summary>

```
{
...
data: {
        pudId: 'f0bdb31f-b243-4f5f-90d7-440f1897d681',
        referenceNumber: "ref-number", // null if no referenceNumber
        prevPrice: 429,
        newPrice: 529
    }
}
```

</details>

<details>

<summary>pud:create</summary>

```
{
...
data: {
        pudId: 'f0bdb31f-b243-4f5f-90d7-440f1897d681',
        referenceNumber: "ref-number", // null if no referenceNumber
    }
}
```

</details>

## 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.&#x20;

#### 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.