Introduction to Webhooks

Webhooks provide a way for our system to send real-time notifications to your server when specific events occur. Instead of your system constantly polling our API to check for new work, we proactively "push" information to you as soon as it's available.

What are Webhooks?

A webhook is an HTTP callback: a structured message sent from our server to a URL you specify. When a relevant event occurs (such as a new fulfilment job being created), our system will make a POST request to your endpoint with a JSON payload containing the event details.

Benefits

  • Efficiency: Reduces the need for frequent, resource-intensive polling of our API.
  • Real-time Updates: Your system is notified immediately when new tasks are available, allowing for faster processing.
  • Reduced Latency: Enables near-instantaneous reactions to fulfilment requirements.
  • Scalability: Minimizes the load on both our API and your infrastructure by only communicating when necessary.

How to Use Them

  1. Set up an endpoint: Create a publicly accessible URL on your server capable of receiving POST requests with a JSON body.
  2. Register your webhook: For the moment, webhooks are set up on request. Please contact support to register your webhook url.
  3. Process the payload: Your endpoint should parse the incoming JSON, identify the event type, and take appropriate action based on the data provided.
  4. Acknowledge receipt: Always return a 200 OK or 204 No Content response to our server to indicate that you have successfully received and processed the webhook. If your server fails to respond with a success code, we will attempt to retry the delivery.

Duplication

You will need to take care to ensure your endpoint is idempotent, meaning that processing the same webhook multiple times will not result in duplication within your system. We send webhook payloads with a unique Idempotency-Key header to help you identify and handle duplicate deliveries. The key is generated using the format ffm_wh_<webhook_id>.

Payload Schema

The webhook payload consists of an event string and a data object containing the job details.

Field Type Description
event string The name of the event.
data object An object containing the event details.