Webhooks

Webhooks deliver real-time HTTP POST notifications to a URL you control whenever key events occur in your BreakGround company. Use them to sync data with your own backend, trigger downstream workflows, or build custom integrations.

Registering an Endpoint

Configure webhook endpoints from Settings > Integrations > Webhooks:

1. Click Add Endpoint.
2. Enter the destination URL (must be publicly reachable HTTPS).
3. Select the event types you want to receive.
4. Save. BreakGround sends a test ping immediately to verify connectivity.

---

Event Types

Event	Fires When
flow.published	A flow transitions to PUBLISHED status
flow.completed	An end user completes all steps of a flow
flow.dismissed	An end user dismisses a flow before completing it
survey.response	An end user submits a survey response
nps.response	An end user submits an NPS score
journey.started	A user is enrolled in a journey
journey.completed	A user completes all steps of a journey
content.published	A content item (tooltip, beacon, announcement, etc.) is published

---

Payload Structure

Every webhook request is an HTTP POST with a JSON body and these headers:

Content-Type: application/json
X-Breakground-Event: <event-type>
X-Breakground-Signature: sha256=<hmac-hex>
X-Breakground-Delivery: <unique-delivery-uuid>

Common fields:

{
  "event": "flow.completed",
  "timestamp": "2026-04-21T12:00:00.000Z",
  "companyId": "t_abc123",
  "data": {
    "flowId": "flow_xyz",
    "flowName": "Onboarding Tour",
    "userId": "user-42",
    "completedAt": "2026-04-21T12:00:00.000Z"
  }
}

The data shape varies by event type. All payloads include event, timestamp, and companyId.

---

Verifying Signatures

BreakGround signs every delivery with HMAC-SHA256 using your endpoint's signing secret. Always verify the signature before processing.

Node.js example:

import crypto from "crypto";

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature),
  );
}

// Express handler
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-breakground-signature"];
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const payload = JSON.parse(req.body);
  // handle payload.event ...
  res.sendStatus(200);
});

Your signing secret is shown once when you register the endpoint. Store it securely — it cannot be retrieved later, only rotated.

---

Retries

If your endpoint returns a non-2xx status or does not respond within 10 seconds, BreakGround retries with exponential back-off:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	8 hours

After 5 failed retries, the delivery is marked failed. You can manually replay deliveries from the Settings > Integrations > Webhooks delivery log.

---

Best Practices

• Respond quickly — Return 200 OK immediately and process asynchronously to avoid timeouts.
• Verify signatures — Always verify X-Breakground-Signature before trusting payload contents.
• Handle duplicates — Use X-Breakground-Delivery as an idempotency key; retries send the same UUID.
• Filter events — Subscribe only to event types your integration needs.