---
title: "New submission events, pushed to your registered endpoint"
method: POST
path: "submission.events"
tags: ["Webhooks"]
---

# New submission events, pushed to your registered endpoint

`POST submission.events` (webhook)

Hedge POSTs this message to each webhook endpoint your brokerage
has registered (broker portal → Settings → Webhooks, admins only)
whenever a submission gains newly-visible events; the SAME event
objects, vocabulary and visibility rules as
`GET /broker/submissions/{submission_id}/events`, delivered
within about a minute of becoming visible. An endpoint receives
events from its creation onward; history is not replayed.

**Verifying.** Every delivery is signed with your endpoint's
`whsec_` secret (shown exactly once at creation; rotate by
revoking and re-creating). Headers are the standard-webhooks /
svix scheme, verifiable with any svix SDK:

- `svix-id`; the delivery id, STABLE across every retry and
  manual redelivery: your idempotency key.
- `svix-timestamp`; unix seconds; reject stale timestamps
  (±5 minutes is the conventional tolerance).
- `svix-signature`; `v1,` + base64(HMAC-SHA256(secret,
  `{id}.{timestamp}.{body}`)) over the exact bytes received.

**Delivery semantics.** At-least-once: dedupe on `svix-id`.
Within one submission, deliveries arrive in order; across
submissions there is no ordering guarantee. An event's `(id,
type)` pair can arrive AGAIN with an upgraded `type`; e.g. a
`status_changed` later re-delivered as `quote_received` once the
quote is relayed to you; so treat `(id, type)` as the event
identity; deduping webhook events by `id` alone will drop quote
arrivals. (The polling feed has no such re-emission; this is
push-only behavior, and it is how a relay that happens hours
after the underlying status row is still pushed to you.)

**Acknowledging.** Respond 2xx within 10 seconds; the body is
ignored. Redirects are treated as failures. Anything else is
retried with backoff for up to 8 attempts over 24 hours; the
delivery is then parked (re-send it from the portal's delivery
log). Repeated exhausted deliveries auto-disable the endpoint;
a successful test-send from the portal re-enables it and queued
events resume.

A `ping` message (`{"type": "ping", ...}`, same signature scheme)
is sent by the portal's test button; acknowledge it like any
other delivery.

**Filtering.** An endpoint's optional `event_types` filter names
the event types it wants (`market_attached`, `quote_received`,
`status_changed`, `declined`, `withdrawn`, `blocked`, `bound`) and
may include `message` to also receive `submission.message`
deliveries (below). No filter = everything.

## Payload

- object
  - `type` 'submission.events', required
  - `submission_id` string, uuid, required
  - `events` object[], required: Newly-visible events, oldest first; the exact object shape of the polling feed's `events` array.
    - `id` string, uuid
    - `type` 'market_attached' | 'quote_received' | 'status_changed' | 'declined' | 'withdrawn' | 'blocked' | 'bound'
    - `occurred_at` string, date-time
    - `market` object
      - `name` string
      - `lines` string[]
      - `lane_id` string, uuid, nullable
      - `category` 'instant_quote' | 'binding' | 'specialty': The Hedge category of a market program, derived from how Hedge submits to it. `instant_quote` ("Hedge Instant Quote"): carrier API, Hedge fills gaps with favorable assumptions and quotes in minutes; every assumption is listed for the retail agent to confirm before bind. `binding` ("Hedge Binding"): carrier portal, Hedge quotes on your behalf. `specialty` ("Hedge Specialty"): email to an underwriter; completed ACORDs, program supplements and loss runs are needed and a human reads them, so Hedge does not assume.
    - `status` string
    - `status_label` string
    - `detail` string, nullable

## Acknowledgement `200`

Acknowledge with any 2xx within 10 seconds; response body is ignored.

---

[API](https://skmtc.dev/hedgespecialty/apis/hedge-submission-api.md) - [All operations](https://skmtc.dev/hedgespecialty/apis/hedge-submission-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedgespecialty/apis/hedge-submission-api/revisions/beefa9cdc11c?raw)