Webhooks
Webhooks let Velosity notify another application when an entity event occurs. Instead of repeatedly polling the API, a receiving system exposes an HTTPS endpoint and Velosity sends the entity representation to it.
Webhooks are useful for ERP synchronization, customer portals, workflow automation, reporting, and notifications. Supported entities include Sales Quotes, Sales Orders, Production Orders, Customers, Trouble Reports, Material Requests, Material Movements, and Product Take-Rate Analyses.
Delivery model
Webhook delivery is asynchronous:
- A Velosity operation succeeds and creates a delivery in the webhook outbox.
- A background worker claims the delivery.
- Velosity sends the configured HTTP request with the entity JSON payload.
- Successful and failed attempts are recorded for diagnostics.
- Transient failures are retried with exponential backoff and jitter.
The business API request does not wait for the receiving system to process the webhook. A successful API response means the Velosity operation and webhook outbox record were committed; it does not mean the external receiver has already accepted the delivery.
Delivery is at least once. Receivers must be idempotent because retries can deliver the same event more than once. Do not rely on delivery order across separate entity changes.
Configuration
Create and manage webhooks in the Velosity Developers area. A webhook configuration identifies:
| Field | Description |
|---|---|
| Entity | Entity whose representation will be delivered. |
| Event | Change that creates the delivery, such as Status Changed or Created. |
| Base URL | Public HTTPS origin for the receiver. |
| Resource | Path appended to the base URL. Use / when the base URL is the complete receiver address. |
| Method | HTTP method. POST is the normal choice. |
| Headers | Optional JSON dictionary of custom request headers. |
| Secret | Optional shared secret used to sign the exact request body. |
| Active | Controls whether new deliveries are created. |
The Detail view provides Edit, Duplicate, Logs, and Test actions. Logs should be the first place to investigate delivery failures.
Entities and events
Common configurations include:
| Entity | Event | Typical use |
|---|---|---|
| Production Order | Status Changed | Notify an ERP or fulfillment system when an order becomes Released, WIP, Completed, On Hold, or Cancelled. |
| Sales Order | Status Changed | Synchronize lifecycle changes such as Released or Completed. |
| Sales Quote | Status Changed | Drive integrations from stable Velosity lifecycle values such as Offered or Accepted. |
Reissuing a Sales Quote deliberately publishes Status Changed with OFFERED, including an OFFERED to OFFERED self-transition. Consumers should process this as a fresh customer offer instead of suppressing it as an unchanged status.
| Sales Quote | Phase Changed | React to an optional, tenant-defined internal workflow label. |
| Sales Quote | Payment Changed | Notify a downstream system of a payment-state change. |
| Customer | Created | Upsert a newly persisted customer into an ERP or CRM. |
| Trouble Report | Status Changed | Synchronize service or quality workflow changes. |
| Material Request | Created | Notify buyer review of a configured-product shortage. This event does not create a purchase order or reserve inventory. |
| Material Movement | Created | Synchronize a recorded production-material movement. |
| Product Take-Rate Analysis | Generated | Consume a newly published take-rate analysis. |
Status is the stable lifecycle contract. Phase is a tenant-defined label that can be renamed, added, or removed. Use a Status Changed event for integrations that must behave consistently across tenants, and use Phase Changed only when the receiver intentionally depends on that tenant's phase configuration.
For production-order status codes, transitions, task behavior, and side effects, see Updating production-order status.
Request format
The request body is the JSON representation of the configured entity. A Production Order / Status Changed webhook includes the full production-order context rather than only the two fields used to make a status PATCH.
The important production-order fields include:
{
"instanceID": "_tenant ID_",
"productionOrderID": "_production order ID_",
"productionOrderNumber": "_order number_",
"status": 4,
"statusText": "Completed",
"salesOrderID": "_sales order ID_",
"salesOrderLineItemID": "_line item ID_",
"phase": "_tenant-defined phase_",
"tasks": []
}
The actual payload can contain additional fields and nested collections. Receivers should ignore properties they do not use so compatible fields can be added without breaking processing. Use instanceID to distinguish tenants or organizations when the receiver handles more than one.
Delivery headers
Every delivery includes a unique delivery header:
X-Velosity-Delivery-Id: _unique delivery ID_
POST deliveries carry the JSON body with Content-Type: application/json. Configured custom headers are also included. Store the delivery ID with the receiver's processing result and use it as an idempotency key.
Signature verification
When a webhook secret is configured, Velosity computes an HMAC-SHA256 signature over the exact UTF-8 request body and sends the lowercase hexadecimal result in:
X-Velosity-Signature: _lowercase hexadecimal HMAC-SHA256_
The receiver should:
- Read the raw request-body bytes before parsing or reformatting JSON.
- Compute HMAC-SHA256 using the shared secret.
- Encode the digest as lowercase hexadecimal.
- Compare the supplied and computed signatures using a constant-time comparison.
- Reject the request when the signature is missing or invalid.
Keep the secret outside source control and application logs. Rotate it when exposure is suspected.
Success, timeouts, and retries
Return a successful 2xx response only after the receiver has durably accepted the event. Velosity uses a 15-second request timeout.
Transient failures are retried up to eight total attempts. Transient conditions include:
- Connection failures and timeouts.
408 Request Timeout.429 Too Many Requests.5xxresponses.
Backoff starts at approximately one minute and doubles for each attempt, with a small random delay, up to six hours. Other 4xx responses are treated as permanent failures and are not retried. Return an accurate status code so Velosity can apply the correct policy.
Receiver requirements
A reliable receiver should:
- Expose a publicly reachable HTTPS endpoint.
- Authenticate requests with the webhook signature or a configured authorization header.
- Deduplicate by
X-Velosity-Delivery-Idor by a durable entity/event key. - Respond quickly after durably queueing or recording the event; perform slow work asynchronously.
- Treat payload snapshots as potentially duplicated or stale and reconcile by entity ID.
- Ignore unknown JSON properties.
- Log the delivery ID, entity ID, response, and processing result without logging secrets.
- Return
429or5xxonly for conditions that should be retried.
Production-order status example
To receive completion notifications, configure:
- Entity: Production Order
- Event: Status Changed
- Method: POST
- Secret: a receiver-specific shared secret
The event is created for every successful production-order status change, not only completion. The receiver must inspect status and act when it equals 4. It should remain safe if the same Completed payload is delivered more than once.
Updating a production order through PATCH /v1/prodorders/status or PATCH /v1/prodorders/{productionOrderID}/completion records the status change and webhook outbox entry in the same transaction. If the outbox entry cannot be created, the status change rolls back. Delivery to the external endpoint occurs later and follows the retry policy above.
Testing and troubleshooting
Use the webhook Test action or a temporary HTTPS request inspector to verify the URL, method, headers, payload, and signature before connecting production processing. Beeceptor provides one option for inspecting test requests: https://beeceptor.com/webhook-integration/
When a delivery is missing or failing:
- Confirm that the webhook is active and configured for the correct entity and event.
- Review the webhook Logs view and locate the delivery ID.
- Confirm that the receiver is publicly reachable over HTTPS.
- Check the returned HTTP status and response body.
- Verify signature calculation against the raw body.
- Confirm that firewalls and proxies allow the request and do not rewrite the body.
- Check whether the receiver already processed the delivery ID before manually replaying it.
For Sales Quote status and phase event timing, see Sales Quote Lifecycle Integration.