Receiving Webhooks

Webhooks allow you to receive real-time notifications when data changes in FreeFallFilms.

Please use this rather than polling the API.

Configuration

Configure your webhook endpoint at freefallfilms.com/webhooks/endpoints.

Payload Format

Webhooks are sent as POST requests with a JSON body:

{
  "event_types": ["booking.created"],
  "dropzone_uuid": "6b1f9e2c-8d3a-4f77-9b0e-2c5a1d4e8f30",
  "model": "Booking",
  "id": 12345,
  "external_id": "your-external-id"
}

Field	Description
`event_types`	Array of event types that triggered this webhook
`dropzone_uuid`	The UUID of the dropzone the record belongs to (shown on the endpoint page in the console)
`model`	The model type: `Booking`, `Filmer`, `Product`, `Jump`, or `FinanceEvent`
`id`	The FreeFallFilms ID of the record
`external_id`	Your external ID (if set on the record)

If you integrate with more than one dropzone, you can use dropzone_uuid to tell which one the notification came from - (though you should still validate with the bearer token).

Event Types

Event	Description
`booking.created`	A new booking was created
`booking.updated`	A booking was updated
`filmer.created`	A new filmer was created
`filmer.updated`	A filmer was updated
`product.created`	A new product was created
`product.updated`	A product was updated
`jump.created`	A jump record was created for a booking
`jump.updated`	A jump record was updated
`finance_event.created`	A financial event was recorded

Event Coalescing

Multiple events for the same record within a short window are coalesced into a single webhook delivery. The event_types array will contain all events that occurred.

For example, if a booking is created, then immediately updated, and that triggers a finance event creation, you may receive:

{
  "event_types": ["booking.created", "booking.updated", "finance_event.created"],
  "dropzone_uuid": "6b1f9e2c-8d3a-4f77-9b0e-2c5a1d4e8f30",
  "model": "Booking",
  "id": 12345
}

Authentication

Verify incoming webhooks by checking the Authorization header matches your signing secret:

Authorization: Bearer your-signing-secret

Responding to Webhooks

Your endpoint should return a 2xx status code to acknowledge receipt.

If your endpoint returns a non-2xx status or times out, delivery will be retried up to 3 times with increasing delays. After all retries are exhausted, the event will be marked as failed.

Failed events can be manually resent from the FreeFallFilms console.

Endpoint Suspension

If your endpoint accumulates 20 consecutive delivery failures, it will be automatically disabled to prevent further failed delivery attempts. You will receive an email notification when this occurs.

To resume delivery, fix the issue with your endpoint and re-enable it in the console.

Handling Webhooks

Treat webhooks as notifications, they do not contain model data. When you receive a webhook:

Acknowledge receipt immediately (return 200)
Use the id or external_id to fetch the current state via the API
Process the updated data

This approach handles out-of-order delivery and ensures you always have the latest data.

Documentation

API