Webhooks

Webhooks let your systems react to activity in Byelabel as it happens, instead of
polling for changes. When an order arrives, a shipment is created, or your balance
changes, Byelabel sends an HTTP POST to a URL you control.

A typical use: your ERP creates a purchase order the moment a shipment is created,
or your accounting system records a charge when your balance changes.

Quick start

In Byelabel, go to Settings → Webhooks and select Add webhook.

Enter the URL that should receive events, give it a name, and choose the events
you want.

Copy the signing secret shown when the webhook is created. It is displayed
once. If you lose it, rotate it to generate a new one.

Build an endpoint that accepts POST, verifies the signature, and replies 200.

Use Send test event on the webhook to confirm delivery end to end.

What a delivery looks like

Byelabel sends a POST with a JSON body:

{
  "event": "shipment.created",
  "timestamp": "2026-10-20T09:14:22.431Z",
  "payload": {
    "id": "a3f1c9d4-7b2e-4c88-91a5-6e0d4f3b8c27",
    "...": "event-specific fields"
  }
}

Headers

Header	Meaning
`X-Webhook-Event`	The event name, matching `event` in the body
`X-Webhook-Id`	Unique id for this delivery. Stable across retries — use it for idempotency
`X-Webhook-Signature`	HMAC-SHA256 of the request body, hex encoded. See Verifying signatures
`X-Webhook-Timestamp`	When the event occurred, ISO 8601
`X-Webhook-Attempt`	Delivery attempt number, starting at `1`
`User-Agent`	Always `ByeLabel-Webhook/1.0`

Any custom headers you configure on the webhook are sent as well. They are applied
after the headers above, so a custom header with the same name will override it.

Body

Field	Type	Notes
`event`	string	The event name
`timestamp`	string	ISO 8601, UTC
`payload`	object \| null	The event data. `null` for events that carry no body

Verifying signatures

Always verify the signature before acting on a webhook. Your endpoint is a public
URL; anyone can post to it. The signature proves the request came from Byelabel.

The signature is HMAC-SHA256 over the raw request body, keyed with your signing
secret, hex encoded.

Use the raw body bytes, not a re-serialized object. If you parse the JSON and
stringify it again, key order and whitespace may differ and the signature will not
match. Most frameworks need to be configured to keep the raw body.

Node.js (Express)

PHP

Python (Flask)

Use a constant-time comparison — timingSafeEqual, hash_equals,
compare_digest — rather than ==.

Rotating the secret

Settings → Webhooks → select the webhook → Rotate secret. The new secret is
shown once and takes effect immediately; deliveries already queued are signed with the
secret in force when they were queued. Plan a short window where your endpoint accepts
either value if you cannot deploy the new secret at the same moment.

Events

Subscribe to specific events, or use a wildcard.

Pattern	Matches
`order.created`	that event only
`order.*`	`order.created`, `order.updated`, `order.deleted`
`*`	every event, including ones added in future

Orders

Event	Sent when
`order.created`	An order is created manually or imported from a marketplace
`order.updated`	Any field on an order changes, including status and address corrections
`order.deleted`	An order is removed

Shipments

Event	Sent when
`shipment.created`	A label is purchased and a shipment is created
`shipment.updated`	A shipment changes — tracking updates, status transitions
`shipment.deleted`	A shipment is voided or removed

Customers

Event	Sent when
`customer.created`	A new recipient record is created
`customer.updated`	A recipient record changes
`customer.deleted`	A recipient record is removed

Products

Event	Sent when
`product.created`	A product is added to the catalogue
`product.updated`	A product changes
`product.deleted`	A product is removed

Batches

Event	Sent when
`batch.created`	A batch is opened
`batch.updated`	Orders are added to or removed from a batch, or it is closed
`batch.deleted`	A batch is removed

Stores

Event	Sent when
`store.synced`	A marketplace store finishes a sync
`store.deactivated`	A store connection is deactivated, usually because credentials stopped working

Account

Event	Sent when
`workspace.updated`	Workspace settings change
`workspace.deleted`	The workspace is closed
`user.created`	A user is added
`user.updated`	A user's details or permissions change
`user.deleted`	A user is removed

Support

Event	Sent when
`ticket.created`	A support ticket is opened
`ticket.updated`	A ticket changes
`ticket.replied`	A reply is added
`ticket.closed`	A ticket is closed

Billing

Event	Sent when
`balance`	Your account balance changes

Responding

Response	Result
`2xx`	Delivery recorded as successful
Anything else	Delivery recorded as failed and retried
No response within 10 seconds	Treated as failed and retried

Reply first, process afterwards. Acknowledge with 200 as soon as you have
verified the signature and stored the event, then do the work asynchronously. If your
processing takes longer than 10 seconds, Byelabel will treat it as a failure and send
the same event again — even though you were handling it correctly.

Response bodies are not interpreted; the first 4 KB is recorded in the delivery log to
help you debug.

Retries

A failed delivery is retried with exponential backoff, starting at 5 seconds and
doubling each time.

With the default of 5 retries:

Attempt	Sent
1	immediately
2	+5 seconds
3	+15 seconds
4	+35 seconds
5	+75 seconds
6	+155 seconds

After the final attempt the delivery is marked failed and is not retried again.

You can set retries per webhook, from 0 (no retries) to 20. Note that 20
retries with doubling backoff spans several days — useful for an endpoint that may be
offline for maintenance, excessive for most integrations.

Idempotency

Retries mean your endpoint must tolerate receiving the same event more than once.
A delivery can also succeed on your side and still be retried, if the response was lost
in transit.

Use X-Webhook-Id as the deduplication key. It stays the same across all attempts of
the same delivery:

Events may also arrive out of order — a retried order.updated can land after a later
one succeeded. Where order matters, compare timestamp against what you hold rather
than assuming arrival order.

Configuration

Setting	Notes
Name	1–150 characters. For your own reference
Target URL	`http` or `https`, up to 500 characters. Use HTTPS in production
Events	At least one. Specific names or wildcards
Enabled	Disable to stop deliveries without deleting the webhook or losing its secret
Max retries	0–20, default 5
Custom headers	Up to 20. Header name up to 100 characters, value up to 2000

Custom headers are useful for a static bearer token or routing hint your gateway
expects. They are not a substitute for verifying the signature.

Monitoring

Open a webhook under Settings → Webhooks to see:

Deliveries — every attempt, with response status, duration and the response body

Statistics — delivery and failure counts over time, error rate, average response
time

A persistent error rate usually means one of: your endpoint is timing out, returning a
non-2xx status, or rejecting signatures because the raw body is being altered before
verification.

Troubleshooting

Signature never matches. The most common cause is verifying against a
re-serialized body. Hash the raw bytes exactly as received. Check also that no proxy
or middleware is rewriting the body, and that the secret matches the webhook you are
receiving from — each webhook has its own.

Deliveries show as timeouts. Your endpoint is taking more than 10 seconds.
Acknowledge first and process in the background.

Duplicate events. Expected behaviour on retry. Deduplicate on X-Webhook-Id.

No deliveries at all. Check the webhook is enabled, that the event you expect is in
its event list, and that your firewall allows inbound requests. Use Send test event
to isolate whether the problem is configuration or connectivity.

Deliveries stopped after working. Check whether the secret was rotated, or whether
the endpoint began returning non-2xx — a webhook is never auto-disabled, so deliveries
continue to be attempted and logged as failures.

Security

Verify every signature, with a constant-time comparison.

Use HTTPS. The payload may contain recipient names and addresses.

Treat the signing secret like a password. Rotate it if it may have been exposed.

Do not rely on source IP addresses for authentication; they are not guaranteed to be
stable.

Return 401 on a signature mismatch rather than 200, so the failure is visible in
your delivery log.

ByeLabel Webhooks

Webhooks#

Quick start#

What a delivery looks like#

Headers#

Body#

Verifying signatures#

Node.js (Express)#

PHP#

Python (Flask)#

Rotating the secret#

Events#

Orders#

Shipments#

Customers#

Products#

Batches#

Stores#

Account#

Support#

Billing#

Responding#

Retries#

Idempotency#

Configuration#

Monitoring#

Troubleshooting#

Security#