> ## Documentation Index
> Fetch the complete documentation index at: https://docs.journeybee.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive supported Journeybee workspace events at a configured connector endpoint

# 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](https://support.journeybee.io) 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.

```javascript theme={null}
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.

## Related

* [Authentication](/guides/authentication) — API key setup
* API Reference — Webhook Events payload reference