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.

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. Topics are types of events that you want to be informed about.

Notifications

The object delivered to a webhook is a notification. 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 it.

Testing webhooks

When testing webhooks, you can run a local server or use a publicly available service such as Beeceptor. If you decide to run a server locally, then you need to make it publicly available using a service such as Pagekite or ngrok. 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 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.

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.

If you are using Cloudflare on your domain, then you should disable it for the registered webhook URL.

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

{
  "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"
        }
      ]
    }
  }
}