Webhooks · Easyflow API

Webhooks are the safest and most reliable way to stay up to date. Instead of asking the API for changes, your server receives an HTTP request from Easyflow as soon as something happens, such as an order being paid or a subscription being canceled.

How it works

You register the URL of an endpoint on your server with Easyflow and choose the events you want to receive.
When one of those events happens, Easyflow sends a POST request to your URL with a JSON body.
Your server processes the event and answers with a 2xx status code.

Payload

Every delivery has the same envelope: the name of the event, when it was sent and its data.

{
  "event": "order.paid",
  "occurredAt": "2025-01-01T12:00:05.000Z",
  "payload": {
    "id": "1a3c5e7a-9c1e-4a5c-8e9a-1c3e5a7c0029",
    "status": "paid",
    "valueInCents": 4990,
    "createdAt": "2025-01-01T12:00:00.000Z"
  }
}

Field	Description
`event`	Name of the event, such as `order.paid`.
`occurredAt`	Date and time when the notification was sent, in UTC.
`payload`	Complete data of the resource at the moment of the event.

The fields of payload depend on the type of the event. The example above is shortened. See the complete payloads below.

Event types

Type	Prefix	Payload
Orders	`order.`	Order events
Subscriptions	`subscription.`	Subscription events
Subscription recurrences	`subscriptionRecurrence.`	Recurrence events
Payments	`payment.`	Payment events

For example, order.paid is sent when an order is fully paid and subscription.canceled when a subscription is canceled. The webhook events page lists every event name.

Receiving events

A minimal receiver in Node.js with Express:

import express from 'express';

const app = express();

app.post('/webhooks/easyflow', express.json(), (request, response) => {
  const { event, payload } = request.body;

  if (event === 'order.paid') {
    markOrderAsPaid(payload.id);
  }

  response.sendStatus(200);
});

app.listen(3000);

Best practices

Answer quickly. Return a 2xx status as soon as you receive the event and do heavy work in the background.
Handle repeated deliveries. When your endpoint fails, the notification is kept in a queue and sent again later. Use the resource id and its status to make your processing idempotent.
Check the current state. Compare the status in the payload with what you have stored, or fetch the resource from the API before taking irreversible actions.
Protect your endpoint. A webhook configuration can include custom headers, such as an Authorization token, that are sent with every delivery. When your webhook has them, check them before trusting a request.
Use HTTPS. Your endpoint receives personal and financial data.