Webhooks

Journeybee sends outbound webhooks to connector endpoints configured for your workspace. There is currently no public API for creating, listing, deleting, or replaying webhook subscriptions. Configure an endpoint through the supported connector provisioning flow in Journeybee. Contact support if you need help with that setup.

Supported events and payloads

Configured endpoints can receive the event identifiers shown in the generated API Reference’s Webhook Events section. That reference defines the payload shape for each event. Requests are POST with a JSON body; the entity key matches the resource, such as lead, deal, partnership, contact, or payment.

Authenticating requests

Each delivery includes:

Content-Type: application/json
Authorization: Bearer <token>
X-Journeybee-Webhook-Delivery-Id, a stable ID for that recipient delivery

The bearer token is an HS256 JWT signed with the connector integration UUID. Verify it before processing the payload. Its claims identify the company, actor, event, and connector settings required by an authorized integration. Treat the integration UUID and every claim as sensitive; do not expose either in browser code or source control.

import jwt from "jsonwebtoken";

app.post("/webhook", (req, res) => {
  const header = req.headers.authorization ?? "";
  const token = header.startsWith("Bearer ") ? header.slice(7) : null;
  if (!token) return res.status(401).end();

  try {
    const claims = jwt.verify(token, process.env.JOURNEYBEE_INTEGRATION_UUID, {
      algorithms: ["HS256"],
    });
    processEvent(claims.event_id, req.body);
    res.status(200).end();
  } catch {
    res.status(401).end();
  }
});

Delivery behavior

Journeybee validates configured webhook targets before every attempt and does not follow redirects. It retries temporary delivery failures, including network errors, timeouts, HTTP 408, HTTP 429, and 5xx responses, for up to five total attempts using exponential backoff. Other HTTP failures and unsafe targets are recorded as terminal delivery failures. Journeybee makes up to five delivery attempts for transient failures, but does not guarantee successful receipt. A receiver can see a duplicate after an uncertain network outcome or source-event replay, and events are not guaranteed to arrive in order. Store and deduplicate X-Journeybee-Webhook-Delivery-Id before doing non-idempotent work, then return a 2xx response promptly. Delivery checks current connector authorization before sending. If access to deal financial features changed after a delivery was queued, commission or payment fields can be omitted from that delivery’s payload. Completed and failed deliveries are retained in Journeybee’s authenticated operator queue view with bounded history. This is operational visibility, not a customer replay interface or a guarantee of successful receipt.

Troubleshooting

Receiving 401s? Verify the bearer JWT with the connector integration UUID and HS256.
Timing out? Persist the delivery ID and payload first, return 2xx, then process the event asynchronously.
Missing delivery? Confirm the endpoint remains configured for the event and contact support with the event time and workspace details.

Authentication — API key setup
API Reference — Webhook Events payload reference

Getting Started

SDKs & Tools

Embedding

Resources

Webhooks

Webhooks

Supported events and payloads

Authenticating requests

Delivery behavior

Troubleshooting

​Webhooks

​Supported events and payloads

​Authenticating requests

​Delivery behavior

​Troubleshooting

​Related

Webhooks

Supported events and payloads

Authenticating requests

Delivery behavior

Troubleshooting

Related