Webhooks

Webhooks let an external system receive real-time notifications when something happens in ProcureSwift — for example, when a purchase order is created, when an invoice status changes, or when a quotation is received. Instead of polling the API, the external system registers a URL and ProcureSwift posts a JSON payload to that URL each time a subscribed event occurs.

Where to find it

In the main menu, open Webhooks (/webhooks). The page requires the Webhooks / View permission.

Available events

A subscription can listen to one or more of the following events:

• purchase_order.created
• purchase_order.status_changed
• invoice.created
• invoice.status_changed
• rfq.published
• rfp.published
• delivery_note.created
• quotation.received
• proposal.received

Creating a webhook subscription

1. Click Add Webhook.
2. Fill in the form:
   • Webhook URL — a publicly reachable HTTPS endpoint that will receive the event payloads. Required.
   • Events — tick at least one event to subscribe to. The webhook is only triggered for the ticked events.
3. Click Create.

One-time secret display

Immediately after creation, the webhook signing secret is shown once in a confirmation dialog. Copy it now and store it securely on the receiving system — the platform will never show it again. The secret is needed to verify that incoming requests genuinely originated from ProcureSwift (see Signature verification below).

Managing subscriptions

The Subscriptions table on /webhooks shows: URL, Events, Status, Last Triggered, consecutive Failures, Created.

Per-row actions:

• Status toggle — flip the switch to activate or deactivate a subscription without deleting it. Deactivated webhooks stop receiving events but their configuration is preserved.
• Edit (pencil icon) — change the URL or the list of subscribed events.
• Delete (trash icon) — permanently remove the subscription.

The Failures column counts consecutive failed delivery attempts. A non-zero value means the receiving endpoint is rejecting requests or is unreachable. Long failure streaks may cause the platform to back off or disable the webhook automatically.

Signature verification (HMAC)

Every webhook request includes a signature header computed from the request body using the subscription's signing secret. The receiving system must verify this signature before trusting the payload — without it, anyone who can guess the URL could post fake events.

The basic verification flow on the receiver:

1. Read the raw request body.
2. Compute HMAC-SHA256(secret, body).
3. Compare the result, in constant time, to the signature header on the request.
4. Reject the request if they do not match.

Store the secret in the receiver's environment configuration — never in source control.

Retries

If the receiving endpoint returns a non-2xx status code or times out, the platform retries the delivery on a backoff schedule. The Last Triggered column shows the most recent attempt (successful or not) and Failures shows how many consecutive attempts have failed since the last success. A successful delivery resets the failure counter to zero.

Rotating the secret

The signing secret is generated when the webhook is created and shown once. To rotate it, delete the subscription and create a new one (which produces a new secret), then update the secret on the receiving system. Coordinate the change so that the receiving system trusts the new secret before the old subscription is removed.

Tips

• Use Edit to add new event types to an existing subscription instead of creating a parallel webhook for each event.
• Make the receiver idempotent — the platform may retry, so the same event could arrive more than once. Use the event ID in the payload to deduplicate.
• Respond with 200 OK as soon as the payload is persisted, and process it asynchronously. Long-running handlers can cause retries.
• Monitor the Failures column or alert when it goes non-zero.

Permissions

Action	Required permission
View subscriptions	Webhooks / View
Add a webhook	Webhooks / Create
Edit a webhook, toggle active	Webhooks / Update
Delete a webhook	Webhooks / Delete

Related guides

• API Keys and Audit Logs — for outbound API calls from your systems into ProcureSwift.