Skip to content

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.

  1. In Shypr, open Settings → Webhooks and add a webhook.
  2. Enter the URL of your endpoint. It must be a public https URL.
  3. Select the events you want.
  4. Open the webhook and copy its secret. You need it to check the signature.
  5. Click Send test. Shypr sends a webhook.test event 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.

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.

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Event: billing.invoice.finalized
X-Webhook-Delivery-Id: 0193a1b2-7c4d-7e5f-8a9b-0c1d2e3f4a5b
X-Webhook-Timestamp: 1767225600
X-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.

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))
}
  • Answer with a 2xx status within 30 seconds. Do the slow work after you answer, for example in a queue.
  • Shypr does not follow a redirect. A 3xx answer 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.