Webhooks

Subscribe to RUC events so Paxon pushes order, work-order and carrier updates to your endpoint instead of polling.

Overview

Webhooks let Paxon push events to your systems as they happen, so you do not have to poll the REST services. You register a destination URL for a topic, and Paxon POSTs a JSON payload to that URL whenever a matching event occurs. Your endpoint acknowledges with HTTP 200.

The Webhook service is one of the OAuth2-secured REST services. Manage subscriptions with a Bearer token as described in the OAuth2 guide. The full request and response schemas are in the Webhook reference.

Managing subscriptions

The service exposes four resources for the subscription lifecycle:

Resource	Purpose
create	Register a new webhook for a topic and destination URL.
patch	Partially update an existing webhook.
delete	Remove a webhook.
get	Fetch the details of a webhook.

Subscription fields

A subscription is defined by the fields below. The required fields are topicName, clientId, facilityCode, url and contentType.

Field	Description
`topicName`	The event topic to subscribe to, e.g. `parcel:load` or `workOrder:completion`.
`clientId`	Your RUC client identifier, issued during onboarding.
`facilityCode`	The facility the subscription applies to, e.g. `EEUK01`.
`url`	Destination URL where Paxon pushes events.
`contentType`	Content type Paxon sets when posting, e.g. `application/json`.
`emailList`	Addresses alerted if the destination is unreachable or errors.
`customHeaders`	Extra headers Paxon sends to the destination, e.g. an API key.
`isPaused`	`0` active, `1` paused. A paused webhook receives no messages.

Creating a webhook

Create a subscription with a POST carrying a Bearer token and the subscription body:

curl -X POST https://ruc-public-api.fulfilit.cloud/v1/webhookService/webhook/create \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "topicName": "parcel:load",
    "clientId": "<clientId>",
    "facilityCode": "EEUK01",
    "url": "https://hooks.acme.example/ruc/events",
    "contentType": "application/json",
    "emailList": ["integrations@acme.example"]
  }'

Event payloads

The payload Paxon pushes depends on the topic.

Work order completion

Subscribe to workOrder:completion to receive a JSON event each time a finished good or a consumed component is reported for a work order. Separate events are pushed for the finished good and for each component. The full schema is documented under the Webhook reference.

Carrier events

Carrier track-and-trace events can also be delivered by webhook. Five representative events span the parcel lifecycle:

Event code	Event
10	Order Received
50	Order Allocated
60	Order Packed
100	Order Despatched
200	Delivered

The field-by-field structure of these payloads, the milestone mapping and the full event list are documented in the Carrier events guide.

Carrier events — the carrier milestone and event payloads in detail.
Integration flow — where webhooks fit end to end.
Webhook reference — request and response schemas.