Webhooks

Webhooks let your system receive real-time notifications when events occur on the Gozem platform, so you can run event-driven integrations instead of polling for changes. When a subscribed event happens, the platform sends an HTTP POST to a URL you configure.

This page covers how webhooks are delivered, secured, and handled. The specific events available are documented by each service in its own section.

Creating a webhook

Webhooks are configured in the Partner Portal. When you create one, you provide:

A webhook can subscribe to several events, and only the events you select are delivered. Each service lists the events it emits in its own section.

Payload structure

Every webhook shares the same envelope:

{
  "guid": "EVT_a1b2c3d4e5",
  "account_guid": "GZ_9f3a2b1c",
  "event_type": "service.resource.action",
  "data": { },
  "environment": "sandbox"
}

Events are delivered only to webhooks that belong to the same account as the API client, are active, and are subscribed to that event type.

Verifying the signature

When a secret is set on the webhook, the platform signs each payload and sends the signature in the X-Webhook-Signature header. The signature is an HMAC SHA-256 of the raw request body using your webhook secret.

Verify it before you process the event: recompute the HMAC over the received body with your secret and compare it to the header. If they do not match, reject the request. This confirms the event came from Gozem and was not altered in transit. Always verify against the raw body, not a re-serialized version, and use a constant-time comparison so the check does not leak timing information.

const crypto = require("crypto");

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody) // the raw request body, not a parsed/re-serialized object
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Example (Express). Capture the raw body, e.g. express.raw({ type: "application/json" }):
app.post("/webhooks/gozem", (req, res) => {
  const valid = verifySignature(req.body, req.get("X-Webhook-Signature"), process.env.GOZEM_WEBHOOK_SECRET);
  if (!valid) return res.status(401).send("invalid signature");

  res.sendStatus(200); // acknowledge fast
  // ...then process the event asynchronously
});

Delivery and retries

Your endpoint should return a 2xx response as soon as it has accepted the event. If it does not respond successfully, the platform retries delivery up to three times with a short delay between attempts before marking the delivery failed. Repeated failures can cause a webhook to be disabled automatically to stop continuous retries.

Because retries happen, the same event can arrive more than once. Handle events idempotently by tracking the event guid and ignoring ones you have already processed.

Handling events well

Respond quickly and do the real work in the background. A handler that does heavy processing inline risks timing out, which the platform reads as a failed delivery and retries.

• Accept events only over HTTPS.
• Verify the signature when a secret is configured.
• Validate the payload shape before acting on it.
• Process asynchronously and keep handling idempotent.
• Log deliveries with their event guid for debugging.

Testing webhooks

Before relying on webhooks in production, confirm your endpoint receives and processes them. Create a webhook in the sandbox environment, subscribe to the events you care about, and trigger them. Some services cannot generate their events naturally in sandbox; where that applies, the service’s own section explains how to trigger them for testing.