# 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=` | **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 } } ```
pud:create ``` { ... data: { pudId: 'f0bdb31f-b243-4f5f-90d7-440f1897d681', referenceNumber: "ref-number", // null if no referenceNumber } } ```
## 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://giremobility.gitbook.io/api/v3/webhooks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.