Webhooks
Webhooks let your integration receive asynchronous notifications about events in your Xemelgo account. When an event occurs, such as a cycle count being created or inventory being updated, Xemelgo sends an HTTP POST request to your configured endpoint.
See Webhook Events for the complete list of event topics and their payloads.
How Webhooks Work
- Register a webhook with your endpoint URL, signing secret, and event topics you want to subscribe to
- Xemelgo sends events to your endpoint asynchronously
- Your endpoint receives the POST request, verifies the signature, and processes the event
- Respond with a
2xxstatus to acknowledge receipt
This event-driven approach reduces the need to poll the API for changes, lowering latency and server load.
When to Use Webhooks
Webhooks are ideal for:
- Near-real-time notifications - Trigger workflows shortly after inventory changes
- Downstream event processing - Record and react to Xemelgo activity in your own systems
- Integration automation - Sync data with external systems
- User notifications - Alert users about important events
Managing Webhooks
Use the GraphQL API to create, list, update, test, and remove webhook subscriptions. See the Webhook Management API reference for every operation, input, and response.
Receiving Webhooks
Webhooks notify your application when events happen in your Xemelgo account. Xemelgo uses HTTPS to send webhook events to your app as JSON payloads that include relevant event data.
Endpoint Requirements
Create an endpoint on your server that can:
- Accept POST requests with a JSON payload
- Return a
2xxstatus quickly (five seconds or less is recommended) - Use a publicly accessible HTTPS URL with a domain name.
localhost, IP addresses, and private network addresses are not supported
Request Format
Headers
| Header | Description |
|---|---|
Content-Type | Always application/json |
xemelgo-delivery-id | Unique delivery identifier. Matches the envelope id and remains available when the payload is sent directly. |
xemelgo-signature | HMAC signature for verifying the webhook (format: sha256=<hex>) |
Body
{
"id": "c1314cc5-60f7-ddba-7be3-900030a8ee05",
"eventTimestamp": 1765572297000,
"topic": "inventory.cycle_count",
"data": {
// Event-specific data
}
}
The topic field identifies the event type, while data contains the event-specific payload. The id uniquely identifies this webhook delivery. It remains unchanged across retries and can be used for deduplication. Separate subscriptions receive separate delivery IDs for the same underlying event.
Verify Webhook Signatures
Xemelgo signs webhook requests so you can verify they originated from Xemelgo and were not modified in transit. Verify every signature before processing its event.
How It Works
Xemelgo generates signatures using HMAC with SHA-256. Each webhook request includes an xemelgo-signature header containing the signature.
To verify:
- Extract the signature from the header (removing the
sha256=prefix) - Compute the HMAC of the raw request body using your signing secret
- Compare both signatures using a constant-time comparison function
Generate a random, high-entropy signing secret and store it in a secrets manager or equivalent secure store. Do not hardcode it, commit it to source control, or write it to logs. You can rotate the secret with the updateWebhook mutation. The replacement is used for deliveries created after the update; a delivery already queued can still use the previous secret.
Handle Webhook Events
Example Webhook Handler Using Express in Node.js
const express = require("express");
const crypto = require("crypto");
const app = express();
// Capture the raw body for the webhook route so the signature is verified against the
// exact bytes Xemelgo sent. express.json() would parse the body, and re-serializing it
// can change the bytes and break the HMAC comparison.
app.use("/webhooks", express.raw({ type: "application/json" }));
const WEBHOOK_SECRET = process.env.XEMELGO_WEBHOOK_SECRET;
function verifyXemelgoSignature(signature, rawBody, signingSecret) {
if (!signature?.startsWith("sha256=")) {
throw new Error("Invalid signature format");
}
const providedSignature = signature.slice(7);
if (!/^[0-9a-f]{64}$/i.test(providedSignature)) {
throw new Error("Invalid signature format");
}
// Compute the HMAC over the exact raw request body bytes that Xemelgo signed.
// Do not parse then re-stringify the body: re-serializing can change the bytes
// (key order, whitespace, unicode) and break the comparison.
const hmac = crypto.createHmac("sha256", signingSecret);
hmac.update(rawBody);
const computedSignature = hmac.digest("hex");
const provided = Buffer.from(providedSignature, "hex");
const computed = Buffer.from(computedSignature, "hex");
const isValid = provided.length === computed.length && crypto.timingSafeEqual(provided, computed);
if (!isValid) {
throw new Error("Signature verification failed");
}
}
app.post("/webhooks", async (req, res) => {
const signature = req.headers["xemelgo-signature"];
try {
verifyXemelgoSignature(signature, req.body, WEBHOOK_SECRET); // req.body is a Buffer
} catch (err) {
console.error("Webhook verification failed:", err.message);
return res.status(401).json({ error: "Unauthorized" });
}
const event = JSON.parse(req.body); // Parse only after verifying
try {
// Replace this with your application's event handling.
await handleWebhookEvent(event);
} catch (err) {
console.error("Failed to process webhook:", err.message);
return res.status(500).json({ error: "Unable to process webhook" });
}
return res.status(200).json({ received: true });
});
app.listen(3000, () => {
console.log("Webhook server running on port 3000");
});
Delivery Behavior
Successful Delivery and Timeouts
Any 2xx response acknowledges a successful delivery. Return it only after your application has accepted the event. Keep processing brief; for longer-running work, save the event and process it asynchronously. Xemelgo stops waiting after 15 seconds and treats the attempt as a timeout.
Retries
Xemelgo makes up to five delivery attempts for network errors, timeouts, 429 responses, and 5xx responses. Other 4xx responses are not retried. A retry can result in your endpoint receiving the same underlying event more than once.
Ordering and Idempotency
Webhook delivery order is not guaranteed. Use the envelope id as the idempotency key for a delivery. It remains unchanged across retries, so store processed IDs and skip an ID your application has already handled. Separate subscriptions receive separate delivery IDs for the same underlying event.
Production Checklist
- Verify each signature against the exact raw request body using a constant-time comparison
- Generate and securely store a random, high-entropy signing secret
- Return a
2xxresponse only after accepting the event for processing - Deduplicate retries using the delivery
id - Keep handlers safe for duplicate and out-of-order delivery