Webhooks
A webhook sends an HTTP POST to your URL when something happens in your workspace: an invoice is finalized, a customer changes, a shipment is created. Use webhooks instead of polling the API.
Set up a webhook
Section titled “Set up a webhook”- In Shypr, open Settings → Webhooks and add a webhook.
- Enter the URL of your endpoint. It must be a public
httpsURL. - Select the events you want.
- Open the webhook and copy its secret. You need it to check the signature.
- Click Send test. Shypr sends a
webhook.testevent to your URL, and shows the answer of your server.
You can also manage webhooks with the GraphQL mutations createWebhook, updateWebhook, enableWebhook, disableWebhook, testWebhook and deleteWebhook. You need the manager role.
Events
Section titled “Events”| Area | Events |
|---|---|
| Billing | billing.invoice.created, billing.invoice.updated, billing.invoice.finalized, billing.invoice.cancelled, billing.quote.created, billing.quote.finalized, billing.sales_order.created, billing.sales_order.cancelled, billing.purchase_order.created, billing.purchase_order.cancelled, billing.credit_note.created, billing.proforma.created |
| CRM | crm.customer.created, crm.customer.updated, crm.supplier.created, crm.supplier.updated, crm.complaint.created, crm.complaint.finalized |
| Inventory | inventory.product.created, inventory.product.updated, inventory.inventory.updated |
| Shipping | shipping.packinglist.created, shipping.packinglist.finalized, shipping.shipment.created, shipping.shipment.cancelled |
An automation can also send a record to a webhook with the step Send to a webhook. That call has the event automation.step.
The request
Section titled “The request”POST /your/endpoint HTTP/1.1Content-Type: application/jsonX-Webhook-Event: billing.invoice.finalizedX-Webhook-Delivery-Id: 0193a1b2-7c4d-7e5f-8a9b-0c1d2e3f4a5bX-Webhook-Timestamp: 1767225600X-Webhook-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
{ "event": "billing.invoice.finalized", "timestamp": 1767225600, "data": { "id": "0193...", "...": "the fields of the record" }}| Header | Meaning |
|---|---|
X-Webhook-Event |
The event. |
X-Webhook-Delivery-Id |
The id of this delivery. A retry has the same id: use it to skip a delivery that you already handled. |
X-Webhook-Timestamp |
The unix time when Shypr signed the request. |
X-Webhook-Signature |
v1= and the HMAC-SHA256 of the signed text, in hex. |
data holds the record with its fields and its relations, as it is after the change.
Check the signature
Section titled “Check the signature”Always check the signature before you trust a request. The signed text is the timestamp, a dot, and the raw body:
{X-Webhook-Timestamp}.{raw request body}Compute the HMAC-SHA256 of that text with the secret of the webhook, put v1= before the hex value, and compare it with X-Webhook-Signature in constant time. Also refuse a timestamp that is older than 5 minutes, to stop a replay.
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verifyShyprWebhook(rawBody, headers, secret) { const timestamp = headers['x-webhook-timestamp'] const signature = headers['x-webhook-signature'] ?? ''
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) { return false }
const expected = 'v1=' + createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')
return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature))}function verifyShyprWebhook(string $rawBody, string $timestamp, string $signature, string $secret): bool{ if (abs(time() - (int) $timestamp) > 300) { return false; }
$expected = 'v1='.hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);
return hash_equals($expected, $signature);}import hashlib, hmac, time
def verify_shypr_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool: if abs(time.time() - int(timestamp)) > 300: return False
signed = timestamp.encode() + b"." + raw_body expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)Answer and retries
Section titled “Answer and retries”- Answer with a
2xxstatus within 30 seconds. Do the slow work after you answer, for example in a queue. - Shypr does not follow a redirect. A
3xxanswer counts as a failure. - Each other answer, a timeout or a network error counts as a failure. Shypr tries a delivery at most 5 times, with a longer wait after each failure (up to 15 minutes).
- After 20 deliveries in a row that failed 5 times, Shypr pauses the webhook and tells the admins of the workspace. Turn it on again in Settings → Webhooks when your endpoint works. The deliveries that wait for a retry go out then.
Settings → Webhooks shows each delivery with its status, the answer of your server and the time it took.