Overview

Webhooks are used to notify your integration when a specific event occurs in your bike-sharing service. They are useful tools to stay synced with Ecovelo or to execute code after a specific event in an asynchronous way.

What are webhooks

A webhook is a set of components that allows to create and send notifications to subscribers after the execution of specific events.

A webhook subscription is a persistant object created by the REST API. It defines the topic(s) of the events the subscriber wants to receive, as well as the destination where these events are sent.

An event is the object sent by a webhook to a webhook subscription. It consists of all the relevant informations about what just happened in the system, including the type of event, called a topic, and the data associated with it.

A topic is the type of events. It defined when events are created and what’s in the payload of those events.

How does it works

You subscribe to a topic and the webhook subscription sends events to the endpoint you specified at subscription.

For example, you create a webhook subscription to the topic trip.created for and HTTPS endpoint hosted in you server. Everytime a trip is created, the webhook subscription sends an event with a trip payload.

Trip are created very often, but instead of continuously polling for creation, you can receive an event when the action occurs.

When to use them

Use case examples:

• Sending a notification (like an email or a SMS) to a user when he creates his account (topic cyclist.created).

• Managing yourself the trip billing when it’s completed (topic trip.terminated).

• Sending a notification to a user who’s riding in a forbidden zone (topic vehicule.position.forbidden).

Webhook ordering

Ordering is not guaranteed for any webhook as we are in a asynchronous system and topics are managed through different channels. For example, it’s possible that a trip.updated event might be delivered before a trip.created event.

Best practices

Here is some good practices to take into account.

Extra topics for endpoints

Having an endpoint configured to receive events from extra topics (or all topics) may overload your system and is not recommanded.

Response to webhooks

After receiving an event, it’s important to respond to the request with an HTTP code < 400 and under 30 seconds.

Otherwise, the webhook will retry to send the event : 5 times, between 10 seconds and 30 mins with an exponantial backoff function.

Implement reconciliation jobs

You shouldn’t only rely on receiving event from Ecovelo to manage your system. Webhook delivery isn’t always guaranteed, and implementing reconciliation jobs to fetch data from Ecovelo is good robustness practice.

Next step

Learn how to set up webhooks for your system.