Developers - Webhooks
Webhooks provide a way for applications to interoperate that doesnt require interfacing with the API. HTTP endpoints (POST) can be set up in your applications that are called by Velosity for various entities, including Sales Quotes, Sales Orders, Production Orders, Customers, and Service Trouble Reports. For example, a webhook could call your application when the status of a Sales Order changes to RELEASED.
If your company has multiple Organizations in Velosity, the InstanceID included in the payload can help you differentiate between the instances.
List
Add
From the list view, click on Add to create a new webhook. At this stage, you will only need to select the entity which is to be passed to your HTTP endpoint. The other properties will be set from the Edit view.
Detail
From the Detail view you can see the various properties of the webhook - as well as Edit, Duplicate, Logs and Test.
Edit
From the Edit view you can update the properties of the webhook.
Entities & Events
- Sales Quote — Status Changed: Use this event for lifecycle-driven integrations. Quote status is a Velosity-defined workflow value; for example, a portal that reacts when a quote is offered or accepted should use this event.
- Sales Quote — Phase Changed: A phase is an optional, tenant-defined internal label. Use this event only when an integration intentionally depends on the tenant's own phase names and configuration.
- Sales Order — Status Changed: Use this event for lifecycle-driven Sales Order integrations, such as a change to
RELEASED. - Sales Quote — Payment Changed: Use this event when a downstream process needs a payment-state change, including a completed card payment. Check the delivered quote's payment status before acting.
- Customer — Created: Sent after a customer record is successfully stored through the Customer create API, including one delivery for each successful customer in a batch request. The payload is the Customer record. This event is not sent for customer updates, contacts, or ship-to addresses.
- Material Request - Created: sent only when a Purchasing or Admin user explicitly sends a configured-product shortage to buyer review. This notification does not create a purchase order or reserve inventory. See Configure Availability and Buyer-Review Integration for setup and payload details.
Sales Quote Status and Phase Events
Sales Quote statuses and phases serve different purposes:
| Value | Ownership | Use for integrations |
|---|---|---|
| Status | Velosity-defined quote lifecycle | Use Status Changed for behavior that must remain consistent across tenants, including Offered and Accepted. |
| Phase | Tenant-defined workflow label | Use Phase Changed only for tenant-specific behavior, such as a local TO SEND, RETURN, or SCRAP label. |
An administrator can associate a Sales Quote phase with a status. When that phase is selected, Velosity attempts the associated status transition; the status changes only when the transition is valid. Changing the status does not automatically change the phase. A phase update can queue two Phase Changed deliveries; the first can contain the previous phase. When the associated status transition succeeds, a Status Changed delivery is queued between those phase deliveries. Receivers must not rely on delivery order and should process duplicate or stale phase snapshots idempotently.
Do not require a tenant to use a particular phase name to drive standard portal or API behavior. If a tenant keeps phases that duplicate lifecycle statuses, such as OFFERED or ACCEPTED, they are optional internal labels; integrations should still key standard behavior from the quote status.
For event timing, payloads, release-mode implications, and receiving-system responsibilities, see Sales Quote Lifecycle Integration.
Customer-created integration
For an ERP customer-master integration, configure a Customer / Created webhook and upsert the delivered customer by customerID. The webhook is queued only after the customer insert succeeds. Delivery is asynchronous, so receivers must accept duplicate deliveries and must not depend on the order of a Customer delivery and a related Sales Quote delivery.
Use the Sales Quote Status Changed and Payment Changed webhooks for quote acceptance and payment workflows. They complement the customer-created webhook; they do not replace the ERP's customer-master upsert.
How to Use
Using a webhook called by the Velosity application requires a publicly accessible host (from the internet). The endpoint must use HTTPS and listen for a POST request. The POST body is a JSON representation of the entity selected for the webhook: a Sales Quote webhook delivers a Sales Quote, a Customer webhook delivers a Customer, and a Sales Order webhook delivers a Sales Order. Check the API documentation for the full entity representation.
Example:
https://yourdomain/velosity/webhook (POST)
The following is an example Sales Order payload. A Sales Quote webhook has the corresponding quote fields, including instanceID, salesQuoteID, and status; see Sales Quote Lifecycle Integration for a Sales Quote example.
{
"instanceID": "ABC",
"salesOrderID": "AB194631-130F-4EA2-A7C9-345B2959C120",
"salesQuoteID": "",
"customer": {
"customerID": "D02B246F-4585-436C-A359-7D5257BC4642",
"customerNumber": "C123",
"customerName": "One Vision INC",
"address": "123 Any St",
"city": "Mountain View",
"state": "CA",
"postalCode": "77434",
"country": "US",
"paymentTerms": "US",
"grossMarginTarget": 20.0,
"notes": [],
"history": [],
"documents": [],
"lineItemTemplates": [],
},
"contacts": [],
"metaData": [],
"status": "DRAFT",
"number": "SO1000",
"description": "",
"purchaseOrder": "",
"discountPercent": 0.00000,
"paymentTerms": "",
"promiseDateUTC": "2024-09-21T23:41:13",
"statusDates": {
"DRAFT": {
"userID": "4617AD42-3F76-46F6-8FC8-B6A598F49C96",
"statusType": "DRAFT",
"createdUTC": "2024-09-11T23:41:12.6114369Z"
}
},
"lineItems": [],
"items": [],
"documents": [],
"history": [],
"notes": [],
"tags": [],
"changeOrders": []
}
Test - Beeceptor
You can test a webhook using Beeceptor: https://beeceptor.com/webhook-integration/
Set up the webhook in Velosity to point to the unique URL Beeceptor generates. Use / for the Resource.
