Real-time push notifications from Leaf Trade to your systems — no polling required. Configure endpoints to receive instant updates when order or product issue statuses change.
Overview
Beta notice: Webhooks are currently in beta. Functionality is available to enabled accounts. If you'd like access or have feedback, contact your Customer Success Manager. |
Webhooks allow Leaf Trade to push data directly to your system the moment a status change occurs — rather than requiring you to repeatedly call our API to check for updates.
This is particularly valuable for teams building ERP integrations, custom order management workflows, or any automation that depends on timely order status data.
How It Works
You configure a webhook in your Leaf Trade vendor dashboard, providing a consumer URL (your endpoint) and optional authentication details.
An object in Leaf Trade — such as an order — undergoes a status change (e.g., moves from New to Approved).
Leaf Trade detects the transition and fires the configured webhook.
An HTTP POST request is sent to your consumer URL containing a JSON payload representing the current state of that object.
The payload sent by a webhook matches the response you would receive from the equivalent Leaf Trade open API endpoint — so if you're already using the API, the data structure will be familiar. |
Configuration
Webhooks are configured from your vendor dashboard under Integrations → Webhooks. Each webhook is configured independently and shares the same global authentication settings.
Authentication
Your consumer endpoint likely needs to verify that incoming requests are genuinely from Leaf Trade. Two methods are supported:
Option 1 — HMAC Signing (Recommended)
HMAC (Hash-based Message Authentication Code) is a widely-used standard for webhook security. Here's how it works:
You generate a shared secret and enter it into the HMAC Webhook signing key field in the dashboard.
When Leaf Trade fires a webhook, it uses that secret to generate a cryptographic signature (checksum) of the payload.
Your endpoint receives the payload and the signature, and can verify they match — confirming the payload came from Leaf Trade and wasn't tampered with.
Leaf Trade uses the SHA-256 hash algorithm for HMAC signing.
If no HMAC secret is entered, Leaf Trade will not include a signature with the payload. Only skip HMAC if your endpoint does not require it or uses header-based authentication instead. |
Option 2 — Custom Headers
If your endpoint requires authorization headers (e.g., a bearer token or API key), you can configure these in the dashboard:
Click + Add Header to add a name-value pair (e.g., Authorization: Bearer your-token).
Multiple headers can be added if needed.
These headers will be included in every webhook request Leaf Trade sends.
Note: Both authentication methods are optional, but we strongly recommend configuring at least one to prevent unauthorized access to your endpoint. |
Available Webhooks
Toggle each webhook on or off individually. When enabled, enter the Consumer URL — the endpoint on your side that Leaf Trade should POST to when the relevant status change occurs.
Webhook | Trigger | Payload | Status |
Order V4 | Order status changes | API V4 Order payload | Available |
Order V3 | Order status changes | API V3 Order payload | Available |
Product Issue | Product issue status changes | API V3 Product Issue payload | Available |
Which order webhook should I use? If you're building a new integration, use Order V4 — it's the most current payload format. Order V3 is available for teams with existing V3 API integrations who want continuity. |
Order Status Changes
Webhooks fire when an order reaches a fully transitioned status. Transitional/intermediate states (such as Approving) will not trigger a webhook POST.
Examples of status changes that will trigger a webhook:
New → Approved
Approved → Revised
Approved → Rejected
Examples of states that will not trigger a webhook:
Approving (in-progress transitional state)
Example Payload
The payload structure for each webhook matches the corresponding Leaf Trade public API response. Below is a simplified example of an Order v4 webhook payload:
{ "count": 420, "previous": null, "results": [ "id": "ord_abc123", "status": "approved", "updated_at": "2025-11-14T18:32:00Z", "vendor_id": 3, "dispensary_location": { "id": 12, "dispensary_id": 14, ... } ... ] }
|
For complete payload schemas, refer to the Leaf Trade API Reference for the corresponding endpoint (V3 or V4 Order, V3 Product Issue).
FAQ
Do webhooks replace the API?
No — webhooks complement the API. Use webhooks when you need to react to status changes in real time. Use the API when you need to query or pull data on demand.
Can I configure multiple consumer URLs for the same webhook?
Currently, each webhook type supports a single consumer URL. If you need multiple endpoints notified, your consumer URL can act as a router on your end that forwards to additional systems.
What happens if my endpoint is down when a webhook fires?
Contact your CSM for current retry behavior — this is an area we're actively developing as part of the beta. We recommend building retry/recovery logic on your end as a best practice.
Can I test webhooks before going live?
Yes. You can use tools like webhook.site or RequestBin as temporary consumer URLs to inspect incoming payloads before connecting your production system.
Are all webhook calls authenticated?
Authentication is optional but strongly recommended. If neither HMAC nor custom headers are configured, Leaf Trade will send the payload without any authentication credentials.
Support & Feature Requests
Webhooks on Leaf Trade are an evolving feature. If you need a webhook type that isn't currently listed, or encounter any issues during setup, reach out to your Leaf Trade Customer Success Manager.
Feature requests for additional webhook triggers are welcomed — your feedback directly shapes the roadmap.