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

# Webhooks

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

[Test Account Setup](test-account-setup)
{% 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:status\_update | Status changes on a PUD |
| pud:price\_update  | Price changes on a PUD  |

{% openapi src="https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbKcRfCOApo6AP6U4kivX%2Fwebhookswagger.json?alt=media&token=80fc25a3-08ea-49b5-b2aa-f0197a9ada8c" path="/api/v3/webhooks" method="post" %}
[webhookswagger.json](https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbKcRfCOApo6AP6U4kivX%2Fwebhookswagger.json?alt=media&token=80fc25a3-08ea-49b5-b2aa-f0197a9ada8c)
{% endopenapi %}

{% openapi src="https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbKcRfCOApo6AP6U4kivX%2Fwebhookswagger.json?alt=media&token=80fc25a3-08ea-49b5-b2aa-f0197a9ada8c" path="/api/v3/webhooks/{id}" method="get" %}
[webhookswagger.json](https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbKcRfCOApo6AP6U4kivX%2Fwebhookswagger.json?alt=media&token=80fc25a3-08ea-49b5-b2aa-f0197a9ada8c)
{% endopenapi %}

{% openapi src="https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbxhQE4hr9hcGHbIBOuBZ%2Fwebhookswagger.json?alt=media&token=90ed052f-a320-4c53-b28b-93eef6205643" path="/api/v3/webhooks" method="get" %}
[webhookswagger.json](https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbxhQE4hr9hcGHbIBOuBZ%2Fwebhookswagger.json?alt=media&token=90ed052f-a320-4c53-b28b-93eef6205643)
{% endopenapi %}

{% openapi src="https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbKcRfCOApo6AP6U4kivX%2Fwebhookswagger.json?alt=media&token=80fc25a3-08ea-49b5-b2aa-f0197a9ada8c" path="/api/v3/webhooks/{id}" method="patch" %}
[webhookswagger.json](https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbKcRfCOApo6AP6U4kivX%2Fwebhookswagger.json?alt=media&token=80fc25a3-08ea-49b5-b2aa-f0197a9ada8c)
{% endopenapi %}

{% openapi src="https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbKcRfCOApo6AP6U4kivX%2Fwebhookswagger.json?alt=media&token=80fc25a3-08ea-49b5-b2aa-f0197a9ada8c" path="/api/v3/webhooks/{id}" method="delete" %}
[webhookswagger.json](https://2378458251-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fk72S9jQc19AzPxqRbV38%2Fuploads%2FbKcRfCOApo6AP6U4kivX%2Fwebhookswagger.json?alt=media&token=80fc25a3-08ea-49b5-b2aa-f0197a9ada8c)
{% endopenapi %}

***

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

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

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

