Contracting API: Webhook Events

The Contracting API publishes webhook events when contracts and contract assignments change. Use these events to keep downstream systems synchronized without polling.

For instructions on how to register an endpoint, verify delivery, and validate signatures, see the Webhooks Quick Start Guide.

Available Events

Contracting Events

Event Type	When It Fires
`contract.updated`	A contract record is created or updated
`contract.assignment.updated`	A contract assignment is created or updated
`contract.assignment.deleted`	A contract assignment is deleted
`contract.assignment_change.updated`	A contract assignment change (workflow task) is created or updated
`contract.assignment_change.deleted`	A contract assignment change is deleted
`contract.packet.submitted`	A contract packet is submitted
`contract.producer_status.updated`	A producer's status within an organization is created or updated
`contract.assignment_changed.updated`	A license record is updated as a result of a contract assignment change

Note: contract.assignment_changed.updated is not listed in the primary reference document — confirm whether it is still active before subscribing.

Producer Profile Events

Producer profile events (id.producer.*) are published by the Producer Profile API, not the Contracting API. See Producer Profile API Webhook Events for the full event catalog and payload schemas.

Event Schema

All Contracting API webhook events share the same envelope:

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.updated",
  "timestamp": "2024-09-30T17:33:00Z",
  "data": {}
}

Field	Type	Description
`id`	string	Unique identifier for this event. Uses the `whe_` prefix. Repeated on retries — use for deduplication.
`type`	string	The specific event type (see table above)
`timestamp`	string (ISO 8601)	UTC time the event was generated
`data`	object	Event-specific payload (see examples below)

Note: The timestamp field is present in observed webhook deliveries but is not listed in the source schema definition. Verify whether it is guaranteed to be present before relying on it.

Example Payloads

`contract.updated`

Fires when a contract record is created or updated. Includes the full current state of the contract.

Field	Type	Description
`contractId`	UUID	Unique identifier for the contract
`agencyOrganizationId` / `toOrganizationId`	UUID	The agency organization — see note below
`agencyOrganizationName` / `toOrganizationName`	String	Name of the agency organization — see note below
`carrierOrganizationId` / `fromOrganizationId`	UUID	The carrier organization — see note below
`carrierOrganizationName` / `fromOrganizationName`	String	Name of the carrier organization — see note below
`personId`	UUID	The producer person record ID
`personNpn`	String	The producer's NPN
`firmId`	UUID	The firm record ID
`firmNpn`	String	The firm's NPN
`assignmentStatusId`	UUID	ID of the assignment status
`assignmentStatusName`	String	Name of the assignment status
`active`	boolean	Whether the contract is currently active
`effectiveDate`	Date	When the contract became effective
`endDate`	Date	When the contract ends (if applicable)
`createdAt`	Date-Time	When the record was created
`updatedAt`	Date-Time	When the record was last updated
`displayNumber`	String	Human-readable contract number
`userDefined1`–`userDefined10`	String	Configurable custom fields

Note: The source document's field table lists agencyOrganizationId/Name and carrierOrganizationId/Name, but the example payload uses toOrganizationId/toOrganizationName and fromOrganizationId/fromOrganizationName. Both naming conventions are included above. Treat the payload field names as the runtime values until this inconsistency is resolved.

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.updated",
  "data": {
    "contractId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "toOrganizationId": "455cd571-abd6-4a0c-950b-28db750e9115",
    "toOrganizationName": "Erin Carrier",
    "fromOrganizationId": "391b9b70-ed4b-4bbc-9eed-a5dff738bb8d",
    "fromOrganizationName": "Independent Insurance Agency",
    "personId": "ed2f7724-947c-4b97-bf1f-2a7ce9c9c1ab",
    "personNpn": "2337860",
    "firmId": "ed2f7724-947c-4b97-bf1f-2a7ce9c9c1ab",
    "firmNpn": "2337860",
    "assignmentStatus": "APPROVED",
    "effectiveDate": "2024-09-26",
    "createdAt": "2024-09-26T14:14:14Z",
    "updatedAt": "2024-09-30T17:33:00Z",
    "displayNumber": "CON-1234"
  }
}

`contract.assignment.updated`

Fires when a contract assignment is created or updated. Contains the full current state of the assignment including commission level, upline, and states.

Field	Type	Description
`contractAssignmentId`	UUID	Unique identifier for the contract assignment
`contractId`	UUID	The parent contract ID
`agencyOrganizationId`	UUID	The agency organization ID
`agencyOrganizationName`	String	Name of the agency organization
`carrierOrganizationId`	UUID	The carrier organization ID
`carrierOrganizationName`	String	Name of the carrier organization
`productName`	String	Name of the product
`productId`	UUID	Product ID
`states`	String	States covered by this assignment
`personId`	UUID	The producer person record ID
`personNpn`	String	The producer's NPN
`firmId`	UUID	The firm record ID
`firmNpn`	String	The firm's NPN
`writingNumber`	String	The writing number for this assignment
`commissionLevelId`	UUID	Commission level ID
`commissionLevelName`	String	Commission level name
`assignmentStatus`	String	Current status (SCREAMING_SNAKE_CASE, e.g. `PENDING_WITH_CARRIER`)
`effectiveDate`	Date	When the assignment became effective
`expirationDate`	Date	When the assignment expires (if applicable)
`requestedEffectiveDate`	Date	The requested effective date
`submittedDate`	Date	Date the assignment was submitted
`referralCodes`	String	Any referral codes attached to the assignment
`uplineNpn`	String	NPN of the upline producer
`uplineId`	UUID	ID of the upline record
`annualization`	Decimal	Annualization period in integer months (e.g. `12`) — see note below
`updatedAt`	Date-Time	When the record was last updated
`responsiblePartyId`	UUID	Responsible party record ID
`responsiblePartyUplineFirmId`	UUID	Responsible party's upline firm ID
`responsiblePartyStartDate`	Date	When the responsible party relationship started
`responsiblePartyEndDate`	Date	When the responsible party relationship ended (if applicable)
`displayNumber`	String	Human-readable assignment number
`userDefined1`–`userDefined10`	String	Configurable custom fields

Note: The annualization field in this event is an integer representing months (e.g. 12). The /v1/annualizations REST endpoint returns a proportion decimal field with no numeric months representation — the two cannot be directly mapped without a lookup.

Note: The assignmentStatus value uses SCREAMING_SNAKE_CASE (e.g. "PENDING_WITH_CARRIER"), consistent with assignmentStatuses.name returned by the REST API. Earlier documentation used human-readable values such as "Active" — these are incorrect.

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.assignment.updated",
  "data": {
    "contractAssignmentId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "toOrganizationId": "455cd571-abd6-4a0c-950b-28db750e9115",
    "toOrganizationName": "Erin Carrier",
    "fromOrganizationId": "391b9b70-ed4b-4bbc-9eed-a5dff738bb8d",
    "fromOrganizationName": "Independent Insurance Agency",
    "productName": "P1",
    "productId": "4008f480-c668-4a2f-ab50-e20bddde8bbf",
    "states": ["AL", "NE"],
    "personId": "ed2f7724-947c-4b97-bf1f-2a7ce9c9c1ab",
    "personNpn": "2337860",
    "firmId": "ed2f7724-947c-4b97-bf1f-2a7ce9c9c1ab",
    "firmNpn": "2337860",
    "writingNumber": "2337860",
    "commissionLevelId": "424183aa-ead8-4a08-b26b-320d00098ba6",
    "commissionLevelName": "Agent - $611",
    "assignmentStatus": "PENDING_WITH_CARRIER",
    "effectiveDate": "2024-09-26",
    "requestedEffectiveDate": "2024-09-26",
    "submittedDate": "2024-09-30",
    "referralCodes": ["XC-555"],
    "uplineNpn": "19785551",
    "uplineId": "dd5c2a40-9166-490d-9ed5-b5cb590a5944",
    "annualization": 0,
    "createdAt": "2024-09-26T14:14:14Z",
    "updatedAt": "2024-09-30T17:33:00Z",
    "responsiblePartyId": "dd5c2a40-9166-490d-9ed5-b5cb590a5944",
    "responsiblePartyStartDate": "2024-10-02",
    "displayNumber": "CA-1234"
  }
}

`contract.assignment.deleted`

Fires when a contract assignment is deleted.

Field	Type	Description
`contractAssignmentId`	UUID	Unique identifier for the deleted contract assignment
`displayNumber`	String	Human-readable assignment number

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.assignment.deleted",
  "data": {
    "contractAssignmentId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "displayNumber": "CA-1234"
  }
}

`contract.assignment_change.updated`

Fires when a contract assignment change (a workflow task representing a status transition or update to an assignment) is created or updated.

Note: The correct event type name is contract.assignment_change.updated (underscore before change). Earlier documentation incorrectly listed this as contract.assignment.change.updated (dot-separated).

Field	Type	Description
`contractAssignmentChangeId`	UUID	Unique identifier for this assignment change record
`contractAssignmentId`	UUID	The associated contract assignment ID
`agencyOrganizationId`	UUID	The agency organization ID
`agencyOrganizationName`	String	Name of the agency organization
`carrierOrganizationId`	UUID	The carrier organization ID
`carrierOrganizationName`	String	Name of the carrier organization
`productName`	String	Name of the product
`productId`	UUID	Product ID
`states`	String	States covered by this assignment change
`personId`	UUID	The producer person record ID
`personNpn`	String	The producer's NPN
`firmId`	UUID	The firm record ID
`firmNpn`	String	The firm's NPN
`writingNumber`	String	The writing number
`taskTypeName`	String	The type of workflow task (e.g. `New Business`)
`referralCodes`	String	Any referral codes
`title`	String	Human-readable title of the assignment change
`contractPacketId`	UUID	Associated contract packet ID (if any)
`newUplineContractAssignmentId`	UUID	New upline assignment ID
`newCommissionLevelId`	UUID	New commission level ID
`newCommissionLevelName`	String	New commission level name
`newAssignmentStatusName`	String	New assignment status (SCREAMING_SNAKE_CASE)
`effectiveDate`	Date	Effective date of the change
`expirationDate`	Date	Expiration date (if applicable)
`newUplineNpn`	String	NPN of the new upline producer
`uplineContractAssignmentChangeId`	UUID	ID of the upline assignment change record
`uplineContractAssignmentChangeDisplayNumber`	String	Display number of the upline assignment change
`newAnnualization`	Decimal	New annualization period in integer months
`createdAt`	Date-Time	When the record was created
`updatedAt`	Date-Time	When the record was last updated
`contractAssignmentChangeDisplayNumber`	String	Human-readable assignment change number

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.assignment_change.updated",
  "data": {
    "contractAssignmentChangeId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "contractAssignmentId": "3ba5965d-1690-49e7-8ee7-69aec9c0cdf5",
    "toOrganizationId": "455cd571-abd6-4a0c-950b-28db750e9115",
    "toOrganizationName": "Erin Carrier",
    "fromOrganizationId": "391b9b70-ed4b-4bbc-9eed-a5dff738bb8d",
    "fromOrganizationName": "Independent Insurance Agency",
    "productName": "P1",
    "productId": "4008f480-c668-4a2f-ab50-e20bddde8bbf",
    "states": ["AL", "NE"],
    "personId": "ed2f7724-947c-4b97-bf1f-2a7ce9c9c1ab",
    "personNpn": "2337860",
    "firmId": "ed2f7724-947c-4b97-bf1f-2a7ce9c9c1ab",
    "firmNpn": "2337860",
    "writingNumber": "2337860",
    "newCommissionLevelId": "424183aa-ead8-4a08-b26b-320d00098ba6",
    "newCommissionLevelName": "Agent - $611",
    "newAssignmentStatus": "PENDING_WITH_CARRIER",
    "effectiveDate": "2024-09-26",
    "expirationDate": "2024-09-26",
    "newUplineNpn": "19785551",
    "uplineContractAssignmentChangeId": "dd5c2a40-9166-490d-9ed5-b5cb590a5944",
    "uplineContractAssignmentChangeDisplayNumber": "CAC-1235",
    "newAnnualization": 0,
    "createdAt": "2024-09-26T14:14:14Z",
    "updatedAt": "2024-09-30T17:33:00Z",
    "displayNumber": "CAC-1234"
  }
}

`contract.assignment_change.deleted`

Fires when a contract assignment change record is deleted.

Field	Type	Description
`contractAssignmentChangeId`	UUID	Unique identifier for the deleted assignment change
`contractAssignmentChangeDisplayNumber`	String	Human-readable assignment change number

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.assignment_change.deleted",
  "data": {
    "contractAssignmentChangeId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "displayNumber": "CAC-1234"
  }
}

`contract.packet.submitted`

Fires when a contract packet is submitted for processing.

Field	Type	Description
`contractPacketId`	UUID	Unique identifier for the contract packet
`submittedByPersonId`	UUID	ID of the person who submitted the packet
`submittedByName`	String	Name of the person who submitted the packet
`submissionDate`	Date-Time	When the packet was submitted
`submissionMethod`	String	How the packet was submitted (e.g. `EMAIL`)
`contractId`	UUID	The associated contract ID
`contractNumber`	String	Human-readable contract number
`submissionUrl`	String	URL to the submitted packet (e.g. PDF link)
`attachments`	JSON	Any attachments included with the submission

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.packet.submitted",
  "data": {
    "contractPacketId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "submittedByPersonId": "abc12345-d678-90ef-gh12-ijkl34567890",
    "submittedByName": "Sarah Adams",
    "submissionDate": "2024-10-28T16:30:00Z",
    "submissionMethod": "EMAIL",
    "contractId": "abc12345-d678-90ef-gh12-ijkl34567890",
    "contractNumber": "CON-1234",
    "submissionUrl": "https://example.com/submission-pdf"
  }
}

`contract.producer_status.updated`

Fires when a producer's status within an organization is created or updated.

Field	Type	Description
`producerId`	UUID	Unique identifier for the producer
`npn`	String	The producer's NPN
`organizationId`	UUID	The organization ID
`organizationName`	String	Name of the organization
`startDate`	Date	When the producer status became effective
`endDate`	Date	When the producer status ends (if applicable)
`statusId`	UUID	ID of the status record
`statusName`	String	Name of the status
`active`	boolean	Whether the status is currently active
`updatedAt`	Date-Time	When the record was last updated

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.producer_status.updated",
  "data": {
    "producerId": "5025c204-5c07-47c6-b9d3-11ad09c35f43",
    "npn": "3654698",
    "organizationId": "7119ddf8-4095-495c-ab59-b2998d72697c",
    "organizationName": "Independent Insurance Agency",
    "startDate": "2024-12-02",
    "endDate": "2025-12-02",
    "statusId": "f19c9ba8-f954-484c-bbf5-442241b14935",
    "statusName": "Active",
    "updatedAt": "2024-12-05T00:03:37Z",
    "active": true
  }
}

`contract.assignment_changed.updated`

Note: This event type is not listed in the primary reference document — confirm whether it is still active before subscribing.

Fires when a license record is updated as a result of a contract assignment change. The data payload contains the updated license record and its lines of authority.

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.assignment_changed.updated",
  "data": {
    "active": true,
    "adhsHomeState": "CO",
    "agentTypes": ["LIFE"],
    "branchId": null,
    "expirationDate": "2028-01-01",
    "forState": "CO",
    "id": 9842341,
    "licenseClass": "Individual",
    "licenseClassCode": "IND",
    "licenseLoas": [
      {
        "ceCompliance": "Compliant",
        "ceCreditsNeeded": 0,
        "ceRenewalDate": "2028-01-01",
        "id": 1234567,
        "issueDate": "2022-06-01",
        "licenseId": 9842341,
        "loa": "Life",
        "loaCode": "LI",
        "loaMapping": {
          "categories": ["Life", null]
        },
        "niprDeleted": false,
        "status": "Active",
        "statusReason": null,
        "statusReasonDate": null,
        "updatedAt": "2026-03-17"
      }
    ],
    "licenseNum": "CO-12345678",
    "niprDateUpdated": "2026-03-17",
    "niprDeleted": false,
    "npn": "15645555",
    "originalIssueDate": "2022-06-01",
    "residencyStatus": "Resident",
    "updatedAt": "2026-03-17"
  }
}

When registering your endpoint in the Svix webhook portal, subscribe to the contract high-level event group to receive all contracting events, or subscribe to specific event types if you only need a subset. To receive producer profile events, subscribe separately — see Producer Profile API Webhook Events.

See the Webhooks Quick Start Guide for step-by-step registration instructions.

Processing Recommendations

Use id for deduplication — if an event is retried, the id stays the same. Store processed event IDs to avoid duplicate processing.
Respond quickly — your endpoint must return 2xx within 5 seconds. Offload heavy processing to a queue or background job.
Validate signatures — verify the webhook-signature header against your signing secret before processing. See Webhooks Quick Start Guide for details.
Log all receipts — log the full event payload and id before processing so you can replay or debug later.
Use updatedAt for ordering — if you receive multiple events for the same resource in quick succession, use data.updatedAt to determine the most recent state.