Priority ERP Webhooks: Pushing Events Out Instead of Polling

Most Priority integrations are built as polling: every few minutes, pull whatever changed through the REST API. It works, but it is slow, expensive in calls, and generates load nobody needs. Priority exposes a webhooks mechanism that inverts the direction - the system pushes an event to you the moment it happens. This is how it actually fits together, and where the traps are.

If you are still scoping the project, the article on integrating with the Priority API covers estimating and planning; this one goes down to the implementation level.

Two objects, not one

This is the first point of confusion. A "webhook" in Priority is not a single thing:

1. The endpoint definition - the Webhook Definitions form, under System Management → System Maintenance → Periodic Maintenance → BPM Maintenance. Here you set a name, a target URL and an authentication token.
2. The rule that fires it - a BPM rule in the flow chart of the relevant document, with action type Webhook, pointing at the endpoint you defined.

Defining the endpoint alone sends nothing. The rule is what binds a business event to an outbound call.

Note also: the Webhooks module licence is required. If it is not present in the installation, none of this planning applies - check that before committing to a client.

Where exactly the rule attaches

The rule sits in the BPM flow chart of the document statuses you want to listen to. For example, to catch shipping documents: Inventory → Inventory Transactions → Sales Inventory Transactions → Statuses for Sales Inv Transacts → BPM Flow Chart-Shipping Docs.

The design implication matters: the trigger is tied to a status change, not to an arbitrary field change. If the business process you want to capture does not manifest as a status transition, you may not have a natural trigger at all - and that is a question for the scoping phase, not something to discover after development starts.

You can add conditions to the rule so the webhook fires only in certain cases - VIP customers only, for instance. Filtering inside Priority beats receiving everything and filtering on your side.

What actually arrives

Headers

The outbound call carries metadata headers identifying exactly what happened:

• priority-form-name - the form it was sent from
• priority-bpm-subject - the BPM subject
• priority-bpm-id and priority-bpm-name - the rule's ID and name
• priority-bpm-token - the authentication token

The token is the only security mechanism. Your endpoint must validate it and reject any request without it - otherwise anyone who discovers the URL can inject forged events. The token is displayed once at creation and then obscured, so copy it immediately.

Request body

The JSON contains the fields you selected in the rule, organised by form or table:

{
  "DOCUMENTS_P": { "PDOCNO": "SH2000000880", "CDES": "David Smith" },
  "DOCTODOLIST": { "OWNERLOGIN": "SteveD" }
}

This shape forces a design decision: the webhook carries only what you selected in advance. It does not bring the full document. In practice there are two approaches:

• Thin webhook - send only the document identifier, then fetch the full document over the REST API. More calls, but always current and resilient to schema changes.
• Fat webhook - send every needed field in the body. Fewer calls, but every new field requires editing the rule inside Priority.

Thin is usually the better default, especially when the integration is maintained by someone without day-to-day access to the ERP.

The real problem: no documented retry

This is the point to design around. There is no documented retry policy. If your server was down, slow, or returned an error, there is no guarantee the event arrives again.

Three consequences follow:

1. Acknowledge fast, process later. The endpoint should validate the token, write the event to a queue or table, and respond immediately. Anything heavy - queries, callbacks into Priority, sending email - must happen asynchronously.
2. Design for duplicates. Even without formal retries, an event can arrive twice from consecutive status transitions. Store a unique identifier per event and skip what you already handled.
3. Keep a reconciliation job. This is the important one. A job that runs daily, pulls documents in the recent time range over the REST API, and compares against what you received. That is what catches whatever the webhook missed.

A webhook without a reconciliation job is not a reliable integration, it is an optimisation. Plenty of projects learn this too late.

The error log

From version 26.0 there is a Webhook - Error Log, in the same BPM Maintenance menu. It retains 7 days only.

Which means: if a webhook fails and nobody reads the log, the evidence disappears within a week - while the missing data stays missing. A simple weekly alert that reads the log is worth building, rather than discovering a gap a month later.

The same version added URL - Cont. and URL - Cont. (2) fields, allowing a URL longer than a single field permits. If your endpoint has a long path or query parameters, that is the answer.

When to use webhooks and when to poll

The architecture that holds up is usually a combination: webhooks for what is urgent, scheduled polling for what is bulky, and a daily reconciliation job that verifies neither one missed anything.