Webhooks

Webhooks are a simple but powerful way to integrate your platform with Open Transport.

What are Webhooks?

A Webhook is a developer provided URL endpoint capable of receiving a POST request upon specific events in Open Transport. For example, it is possible to provide a Webhook for a Vehicle, which will receive a request when a booking is attempted.

This allows you to take action on your end such as writing logs, initiating notifications, etc. before making additional API requests into Open Transport.

Specifying Webhooks

When you create a resource, there is often a webhooks object which contains a map of event names to URLs:

{
    // other fields
    "webhooks": {
        "event-key": "https://domain.com/path/to/webhook"
    }
}

When the event-key event occurs in the system, Open Trnsport makes a request to the specified URL.

Storing state

The body of a Webhook request will contain a payload that provides some context to the event that has occurred, such as any relevant IDs or other values. If you want to store additional state, you can do so by appending URL parameters to the URL. Open Transport will ignore them, but they will be still be present in the URL when the Webhook is triggered, allowing you to extract them and use them.

For example, for additional security, you might decide to include an access token that hashes the Webhook URL with a secret string allowing you to verify that the incoming request is real.

Webhook server

Writing a Webhook server is as trivial as listening to incoming HTTP requests.

Requests

A Webhook request is a POST request containing a JSON body that resembles the following object:

{
    "event": "event-key",
    "data": {
        "something": true
    }
}
  • event-key - (string) Key describing the kind of event
  • data - (object) Event specific data structure (see object documentation for details)

Responses

The developer’s Webhook listener server must reply with a 200 OK response as quickly as possible. Any other non-200 response will cause the request to be made again after an unspecified period; usually moments later.

Eventually, if no requests are successful within acceptable timeouts, the operation will be cancelled and no further attempts will be made.

See also