Notifications and events

Three ways to hear what happens on your files:

• Notification settings decide which emails Hedge sends your brokerage, to whom, and whether they also go to your webhooks.
• The events feed, GET /broker/events, is one poll for every file in your brokerage.
• Webhooks push the same events to your endpoint as they happen.

Notification settings

In the broker portal, Settings → Notifications lists the events Hedge notifies you about:

Event
Submission received	Hedge has the file.
Info needed	A market needs an answer from you.
Quote ready	A quote is in. The email attaches the quote PDFs. Always emailed.
Declined / not a fit	A market declined or can’t write the risk.
Bind updates	Progress on a bind.
Policy issued and documents	The policy and its documents. Always emailed.
Payment reminders	Reminders about an unpaid invoice.

For each event you choose:

• on or off;
• recipients: the file’s producer, your brokerage’s team inbox, and up to five extra addresses;
• channel: email, webhook, or both.

A brokerage admin sets the brokerage defaults. Any user can override an event for the files they produce; a personal override covers email only, because webhook endpoints belong to the whole brokerage. With nothing set, Hedge sends what it always has. Settings apply to every file, however it was created: portal, email, API or MCP.

Quote and policy emails can’t be turned off. The quote email is how Hedge releases an approved quote to you, and the quote_received event and its webhook fire after it. The policy email delivers the binder, the policy and its documents. For these two you choose who receives the email (and, for quotes, whether webhooks also fire), not whether it is sent.

Note

Settings can turn an email off or send it to different people. They never force a send: Hedge’s own review still decides whether and when an email goes out. Two emails are not governed by the settings: the request to confirm before a bind goes to the person who ordered the bind, because it carries their sign-in link, and payment reminders addressed to the insured go to the insured.

The events feed

GET /broker/events is the brokerage-wide change feed: one poll instead of one per file.

curl "https://api.hedgespecialty.com/api/v1/broker/events?since=$CURSOR&limit=50" \
  -H "Authorization: Bearer $HEDGE_TOKEN"

{
  "events": [
    {
      "id": "8c0f…",
      "submission_id": "0694932d-…",
      "type": "quote_received",
      "occurred_at": "2026-10-29T18:04:11Z",
      "market": { "name": "Coterie", "lines": ["general_liability"], "lane_id": "…", "category": "instant_quote" },
      "status": "quoted",
      "status_label": "Quoted",
      "detail": null,
      "documents": [
        { "kind": "hedge_quote_pdf", "file_name": "Hedge quote.pdf",
          "download_path": "/api/v1/broker/finalized-documents/5b1e…/pdf", "carrier_url": null }
      ]
    }
  ],
  "next_cursor": "…"
}

• Event type is one of market_attached, quote_received, status_changed, declined, withdrawn, blocked and bound.
• quote_received events carry the quote’s documents, the same entries the quote read lists. documents is null on every other type.
• The end of the stream is a null cursor, never a short page. A non-null next_cursor means more events may exist: store it and poll again with since=<cursor> until you get a null. A page can hold fewer than limit events, or none, and still have a cursor. Resume later polls from your last non-null cursor, and dedupe by event id.
• limit is clamped to 1 to 100 (default 50).
• GET /broker/submissions/{id}/events is the same feed for one file.

With the CLI:

hedge events                    # from the beginning, to the tail
hedge events --since <cursor>   # only what is new

Tip

Polling one file while it quotes? GET /broker/submissions/{id}/instant-quotes returns each market’s current state; poll it every 5 to 10 seconds while a market is preparing or quoting. Use the events feed for everything else.

Webhooks

Instead of polling, register a webhook endpoint in the broker portal under Settings → Webhooks (brokerage admins). The management API is portal-only on purpose, so a leaked API key can never point your event stream somewhere new. Endpoints created in the sandbox portal receive sandbox deliveries.

Hedge POSTs two payload types:

type	When	Body
submission.events	A file gains new events	{ type, submission_id, events[] }, the same event objects as the feed
submission.message	A new message on a file’s thread	{ type, submission_id, message }

• Filter with the endpoint’s optional event_types: any event type above, plus message for thread messages. No filter means everything. Events switched off for webhooks under Settings → Notifications are not sent, and are not replayed when you switch them back on.
• Verify each delivery’s svix-style signature (svix-id, svix-timestamp, svix-signature) with the endpoint’s whsec_ secret, shown once when you create it.
• Acknowledge with any 2xx within 10 seconds. Anything else is retried with backoff for up to 24 hours.
• Dedupe on svix-id, which is stable across retries. Delivery is at-least-once and in order within a file. An event can arrive again with an upgraded type (a status_changed re-delivered as quote_received once the quote reaches you), so treat (id, type) as the event’s identity.
• An endpoint receives events from its creation onward; history is not replayed.

The full contract is under the Webhooks tag in the API Reference.