# Webhooks ## Overview Webhooks are a powerful resource that you can use to automate your use cases and improve your productivity. [You can find more about them through this link if you're unfamiliar](https://requestbin.com/blog/working-with-webhooks/). Unlike the API resources, which represent static data that you can create, update and retrieve as needed, webhooks represent dynamic resources. You can configure them to automatically notify you when a customer has taken a particular action, such as reporting a wrong address or visiting the tracking page. The main concepts for webhooks are **subscriptions**, **topics**, and **notifications**. ### Subscriptions A webhook **subscription** listens for **notifications** on a **topic** you want to be notified about. You can register a webhook subscription on your Dashboard in *Settings->Developer*. ### Topics A **subscription** will listen for one or more [topics](#webhook-topics). Topics are types of events that you want to be informed about. ### Notifications The object delivered to a webhook is a [notification](#webhook-notification-object). Notifications have payloads, which contain the result of a customizable *(talk to your Kublau administrator)* GraphQL API payload for the related objects of the event. ## Configuring webhooks You can configure your webhooks using the Kublau dashboard: 1. From your Kublau dashboard, go to **Settings** > **Developer**. 2. In the **Webhooks** section, click **Create a webhook**. 3. Select the topics you want to listen for and the URL where you want to receive notifications. After you've created a webhook, you're presented with a secret to validate its integrity. You can also [test](#testing-webhooks) it. ### Testing webhooks When testing webhooks, you can run a local server or use a publicly available service such as [Beeceptor](https://beeceptor.com/). If you decide to run a server locally, then you need to make it publicly available using a service such as [**Pagekite**](https://pagekite.net/) or [**ngrok**](https://ngrok.com/). The following URLS do not work as endpoints for webhooks: * Localhost * Internal network * Domains like `www.example.com` * Kublau domains such as `kublau.com` and `api.kublau.com` To test your webhook from the Kublau dashboard: 1. Go to the **Webhooks** section in **Settings** > **Developer**. 2. Click **Send test notification** next to the webhook that you want to test. 3. Select the **topic** you want to test. An example webhook is sent to the configured webhook URL. ### Creating an endpoint for webhooks Your endpoint must be an HTTPS webhook address with a valid SSL certificate that can correctly process event notifications as described below. You must also implement [verification](#verifying-webhooks) to make sure webhook requests originate from Kublau. #### Payloads Payloads contain a JSON object with the data for the webhook event. The contents and structure of each payload varies depending on the [subscribed topic](#webhook-topics). #### Receiving a webhook After you register a webhook URL, Kublau issues an HTTP POST request to the URL specified every time that event occurs. The request's POST parameters contain JSON data relevant to the event that triggered the request. {% hint style="warning" %} If you are using Cloudflare on your domain, then you should disable it for the registered webhook URL. {% endhint %} Kublau verifies SSL certificates when delivering payloads to HTTPS webhook addresses. Make sure your server is correctly configured to support HTTPS with a valid SSL certificate. ### Responding to a webhook Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the `200` range, including `3XX` HTTP redirection codes, indicates that you did not receive the webhook. Kublau does not follow redirects for webhook notifications and considers them to be an error response. ### **Frequency** Kublau has implemented a five second timeout period and a retry period for subscriptions. Kublau waits five seconds for a response to each request to a webhook. If there is no response, or an error is returned, then Kublau retries the connection 5 times over the next 48 hours. If there are 5 consecutive failures, then the webhook notification is dropped. To avoid timeouts and errors, consider deferring app processing until after the webhook response has been successfully sent. ### Verifying webhooks In order verify that the webhook is being sent by Kublau you need to verify that the value of the `X-Kublau-Token` HTTP header matches the Shared Secret Token given to you on the Webhooks section in **Settings** > **Developer**. If they match, then you can be sure that the webhook was sent from Kublau. ## Data reference ### Webhook Topics The following topics are available and you can be notified when an action relating to that topic occurs. You just need to tell us where to send the notification. The `Data Type` column shows the API type that will be sent as the data of the notification. | Topic | Data Type | Description | | ---------------- | --------- | ------------------------------ | | TRACKER\_CREATED | Tracker | Subscribe to tracker creations | | TRACKER\_UPDATED | Tracker | Subscribe to tracker updates | | EVENT\_CREATED | Event | Subscribe to events | ### Webhook Notification Object A notification object contains the following fields: The contents of `data` object will be defined according to its `type` field. In the example to the right, the type value of `Tracker` indicates a tracker object. Values are formatted according to the schema defined for the type in our GraphQL Schema. | Attribute | Type | Description | | ----------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | topic | String | Corresponds to a topic. | | data | Object | The data payload associated with the notification. | | data.RESOURCE\_NAME.ATTRIBUTE\_NAME | Object | A payload may have multiple resources. Each resource is scoped under a key representing it's type: order, tracker, customer, shipment, ... | ```javascript { "topic": "TRACKER_UPDATED", "data": { "tracker": { "id": "gid://kublau/Tracker/6ca38b22-1f3d-45de-b977-6531afcda7f8", "carrier": "FEDEX", "deliveredAt": null, "estimatedDeliveryAt": null, "signedBy": null, "trackingCode": "7279143125", "status": "DELIVERED", "checkpoints": [ { "id": "gid://kublau/Checkpoint/22b232e3-3479-4dca-a3de-2f1854789799", "message": "Hemos recibido tu orden de envío", "scannedAt": "2021-09-14T19:17:39Z", "status": "PENDING" }, { "id": "gid://kublau/Checkpoint/8b369979-b17e-401c-bc1c-fb58578005c9", "message": "Ya tenemos tu paquete", "scannedAt": "2021-09-17T18:46:42Z", "status": "PICKED_UP" }, { "id": "gid://kublau/Checkpoint/cbbbf062-cb15-49ab-ab80-e9de76a44ef9", "message": "En la estación", "scannedAt": "2021-09-17T22:48:23Z", "status": "IN_TRANSIT" }, { "id": "gid://kublau/Checkpoint/1fa76e15-ab14-45d0-acf2-2e3c2d318b2c", "message": "Entre almacenes", "scannedAt": "2021-09-18T01:13:52Z", "status": "IN_TRANSIT" }, { "id": "gid://kublau/Checkpoint/e86ed49c-17de-44f7-a5a5-4bd7a7fbf91a", "message": "En la estación", "scannedAt": "2021-09-18T04:07:33Z", "status": "IN_TRANSIT" }, { "id": "gid://kublau/Checkpoint/a6d761b9-ad10-4ef7-a401-b48910050629", "message": "Entre almacenes", "scannedAt": "2021-09-18T04:09:07Z", "status": "IN_TRANSIT" }, { "id": "gid://kublau/Checkpoint/570d7e0e-b1f5-49a9-9bd3-9e21f94ed25c", "message": "Entregado y recibio por Juan Perez", "scannedAt": "2021-09-19T13:53:59Z", "status": "DELIVERED" } ] } } } ``` ##