Hedge Webhooks API

openapi: 3.2.0
info:
  title: Hedgespecialty Com Webhooks API
  version: '1.0'
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: hedge-openapi.json, hedgespecialty-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.hedgespecialty.com/api/v1
  description: Production
- url: https://staging-api.hedgespecialty.com/api/v1
  description: Staging sandbox
security:
- brokerOAuth: []
tags:
- name: Webhooks
paths: {}
webhooks:
  submission.events:
    post:
      tags:
      - Webhooks
      operationId: receiveSubmissionEvents
      summary: New submission events, pushed to your registered endpoint
      description: '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.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - submission_id
              - events
              properties:
                type:
                  type: string
                  const: submission.events
                submission_id:
                  type: string
                  format: uuid
                events:
                  type: array
                  description: Newly-visible events, oldest first; the exact object shape of the polling feed's `events` array.
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      type:
                        type: string
                        enum:
                        - market_attached
                        - quote_received
                        - status_changed
                        - declined
                        - withdrawn
                        - blocked
                        - bound
                      occurred_at:
                        type: string
                        format: date-time
                      market:
                        type: object
                        properties:
                          name:
                            type: string
                          lines:
                            type: array
                            items:
                              type: string
                          lane_id:
                            type: string
                            format: uuid
                            nullable: true
                          category:
                            $ref: '#/components/schemas/ProgramCategory'
                      status:
                        type: string
                      status_label:
                        type: string
                      detail:
                        type: string
                        nullable: true
      responses:
        '200':
          description: Acknowledge with any 2xx within 10 seconds; response body is ignored.
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
  submission.message:
    post:
      tags:
      - Webhooks
      operationId: receiveSubmissionMessage
      summary: A new thread message (Hedge's or yours), pushed to your endpoint
      description: 'Hedge POSTs this message whenever a new message becomes visible

        on a submission''s thread; the SAME object, vocabulary and

        visibility rules as `GET /broker/submissions/{submission_id}/thread`

        (Hedge''s emails to your brokerage, your replies, and assistant

        chat in both directions; never carrier or insured correspondence),

        delivered within about a minute of becoming visible. One message

        per delivery; a burst arrives as consecutive deliveries in order.

        An endpoint receives messages from its creation onward (and, for

        endpoints that predate this message type, from the moment it

        shipped); history is not replayed.


        Signing, `svix-id` dedupe, at-least-once delivery, in-order

        delivery within a submission, acknowledgement and retry rules are

        exactly those of `submission.events`. Messages never re-arrive

        with a changed body; dedupe on `svix-id` (or on `message.id`).

        Delivered to endpoints whose `event_types` filter is empty or

        includes `message`.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - submission_id
              - message
              properties:
                type:
                  type: string
                  const: submission.message
                submission_id:
                  type: string
                  format: uuid
                message:
                  $ref: '#/components/schemas/ThreadMessage'
      responses:
        '200':
          description: Acknowledge with any 2xx within 10 seconds; response body is ignored.
    servers:
    - url: https://api.hedgespecialty.com/api/v1
      description: Production
    - url: https://staging-api.hedgespecialty.com/api/v1
      description: Staging sandbox
components:
  schemas:
    ThreadMessage:
      type: object
      description: 'One broker-facing message on a submission, normalized across

        channels. `direction` is relative to Hedge: `inbound` = your

        brokerage wrote it (an email reply, or a message sent through

        `POST .../thread` or the portal assistant), `outbound` = Hedge

        wrote it. `channel` is `email` for emails Hedge exchanged with

        your brokerage and `chat` for assistant-chat rows; `from`/`to`

        are email addresses and are null/empty on chat rows.

        '
      required:
      - id
      - channel
      - direction
      - kind
      - occurred_at
      - body_text
      properties:
        id:
          type: string
          format: uuid
        channel:
          type: string
          enum:
          - email
          - chat
        direction:
          type: string
          enum:
          - inbound
          - outbound
        kind:
          type: string
          description: The email's type (e.g. initial_clearance, market_plan_update, quote_delivery, broker_reply) or `chat`.
        occurred_at:
          type: string
          format: date-time
        subject:
          type: string
          nullable: true
        body_text:
          type: string
          description: Plain text. HTML-only emails are converted server-side.
        from:
          type: string
          nullable: true
        to:
          type: array
          items:
            type: string
        attachments:
          type: array
          items:
            type: object
            required:
            - name
            properties:
              name:
                type: string
              download_path:
                type: string
                nullable: true
                description: Present when the file is a finalized document you can fetch via `GET /broker/finalized-documents/{document_id}/pdf` (relative to the base URL).
        in_reply_to:
          type: string
          nullable: true
          description: RFC 5322 Message-ID this email replied to, when known.
        delivered_via:
          type: string
          enum:
          - email
          - partner
          nullable: true
          description: How a Hedge-written message reached you. `partner` means it was delivered to a partner app's thread (for example Hedge Connector) instead of being emailed. Null for your own messages and chat rows.
    ProgramCategory:
      type: string
      enum:
      - instant_quote
      - binding
      - specialty
      description: '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.

        '
  securitySchemes:
    brokerOAuth:
      type: oauth2
      description: 'Broker access token. Scopes: `broker_mcp` (read), `broker_submit`

        (write). Per-user tokens come from the OAuth authorization-code +

        PKCE flow (`/oauth/authorize` → `/oauth/token`); machine tokens

        from `client_credentials`, using an API key created self-serve in

        the broker portal (Settings → API keys) or issued by Hedge ops.

        Access tokens live 60 minutes.

        '
      flows:
        authorizationCode:
          authorizationUrl: https://api.hedgespecialty.com/api/v1/oauth/authorize
          tokenUrl: https://api.hedgespecialty.com/api/v1/oauth/token
          scopes:
            broker_mcp: Read brokerage-scoped submissions, policies, payments, appetite, and requirements.
            broker_submit: Create submissions, answer Hedge's asks, and act on quotes for your brokerage.
        clientCredentials:
          tokenUrl: https://api.hedgespecialty.com/api/v1/oauth/token
          scopes:
            broker_mcp: Read brokerage-scoped submissions, policies, payments, appetite, and requirements.
            broker_submit: Create submissions, answer Hedge's asks, and act on quotes for your brokerage.
externalDocs:
  description: Hedge developer documentation
  url: https://docs.hedgespecialty.com
x-refined-from:
- hedge-openapi.json
- hedgespecialty-com-openapi.yml