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.deleted`	A contract record is deleted
`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.responsible_party.updated`	A contract's responsible party is created or updated
`contract.responsible_party.deleted`	A contract's responsible party is deleted
`hierarchy.producer.added`	A producer is newly placed under an upline in a hierarchy
`hierarchy.producer.changed`	An existing producer's hierarchy position (upline and/or commission level) changes
`hierarchy.producer.relationship.terminated`	A producer's hierarchy relationship ends — its contract assignment transitions into a terminal status

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
`responsibleUplineFirmId`	UUID	ID of the upline firm responsible for this contract
`responsibleUplineFirmNpn`	String	NPN of the upline firm responsible for this contract
`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)
`contractCompletionDate`	Date	When contracting completed, from the contract's latest active contract assignment
`states`	String	State abbreviations covered by the contract's active contract assignments; empty when there are no active assignments
`createdAt`	Date-Time	When the record was created
`updatedAt`	Date-Time	When the record was last updated
`displayNumber`	String	Human-readable contract number
`parentContractId`	UUID	ID of the parent contract, if this is a subsidiary contract
`parentContractDisplayNumber`	String	Display number of the parent contract, if this is a subsidiary contract
`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",
    "responsibleUplineFirmNpn": "7654321",
    "assignmentStatus": "APPROVED",
    "active": true,
    "effectiveDate": "2024-09-26",
    "contractCompletionDate": "2024-10-01",
    "states": ["AL", "NE"],
    "createdAt": "2024-09-26T14:14:14Z",
    "updatedAt": "2024-09-30T17:33:00Z",
    "displayNumber": "CON-1234"
  }
}

`contract.deleted`

Fires when a contract record is deleted. Only the contractId is included, since no other state is meaningful once the record is gone.

Field	Type	Description
`contractId`	UUID	Unique identifier for the deleted contract

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.deleted",
  "data": {
    "contractId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5"
  }
}

`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
`createdAt`	Date-Time	When the record was created
`updatedAt`	Date-Time	When the record was last updated
`responsiblePartyId`	UUID	Responsible party record ID
`responsibleUplineFirmId`	UUID	ID of the upline firm responsible for this contract assignment
`responsibleUplineFirmNpn`	String	NPN of the upline firm responsible for this contract assignment
`responsiblePartyStartDate`	Date	When the responsible party relationship started
`responsiblePartyEndDate`	Date	When the responsible party relationship ended (if applicable)
`displayNumber`	String	Human-readable assignment number
`contractDisplayNumber`	String	Display number of the contract the assignment belongs to
`contractAssignmentChangeIds`	UUID	IDs of the assignment's non-terminal (open) contract assignment
`uplineContractAssignment`	Object	Curated identity of the assignment's upline (`id`, `displayNumber`, `firmName`, `personName`); `null` when there is no upline
`externalNotes`	String	External notes on the contract assignment
`debitBalance`	Decimal	Debit balance of the contract assignment (up to 12 digits, 2 decimal places)
`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",
    "responsibleUplineFirmNpn": "7654321",
    "responsiblePartyStartDate": "2024-10-02",
    "displayNumber": "CA-1234",
    "contractDisplayNumber": "CON-1234",
    "contractAssignmentChangeIds": ["dd0e8400-e29b-41d4-a716-446655440007"],
    "uplineContractAssignment": {
      "id": "cc0e8400-e29b-41d4-a716-446655440008",
      "displayNumber": "CA-00009",
      "firmName": "Upline Agency LLC",
      "personName": "Jane Doe"
    }
  }
}

`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).

Getting Previous Values (Callback Required)

The payload for this event includes the new state of each changed field (indicated by the new prefix, e.g. newCommissionLevelId, newCommissionLevelName). It does not include the previous values.

To determine what a field was before the change, call:

GET /v1/contractAssignmentChanges/{contractAssignmentChangeId}

The API response includes the previous values. Combined with the new* fields in the webhook payload, you have the full before/after picture.

This pattern applies to all change-type webhook events — not just commission changes. If you need to track deltas (e.g. "commission changed from X to Y", "upline changed from A to B"), plan for this callback as part of your event processing.

Field	Type	Description
`contractAssignmentChangeId`	UUID	Unique identifier for this assignment change record
`contractAssignmentId`	UUID	The associated contract assignment ID
`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 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
`uplineContractAssignmentChange`	Object	Curated identity of the upline assignment change (`id`, `displayNumber`, `firmName`, `personName`); `null` when there is no upline
`responsibleUplineFirmNpn`	String	NPN of the upline firm responsible for this contract assignment
`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
`userDefined1`–`userDefined10`	String	Configurable custom fields

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.assignment_change.updated",
  "data": {
    "contractAssignmentChangeId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "contractAssignmentId": "3ba5965d-1690-49e7-8ee7-69aec9c0cdf5",
    "contractId": "110e8400-e29b-41d4-a716-446655440009",
    "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",
    "uplineContractAssignmentChange": {
      "id": "dd5c2a40-9166-490d-9ed5-b5cb590a5944",
      "displayNumber": "CAC-1235",
      "firmName": "Upline Agency LLC",
      "personName": "Jane Doe"
    },
    "responsibleUplineFirmNpn": "7654321",
    "newAnnualization": 0,
    "createdAt": "2024-09-26T14:14:14Z",
    "updatedAt": "2024-09-30T17:33:00Z",
    "displayNumber": "CAC-1234",
    "userDefined1": "Region West"
  }
}

`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.responsible_party.updated`

Fires when a contract's responsible party is created or updated.

Field	Type	Description
`id`	UUID	Unique identifier of the contract responsible party
`contractId`	UUID	The contract the responsible party belongs to
`contractDisplayNumber`	String	Display number of the contract
`responsiblePartyId`	UUID	The party responsible for the contract
`startDate`	Date	When the responsible-party window begins
`endDate`	Date	When the responsible-party window ends; `null` when open-ended

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.responsible_party.updated",
  "data": {
    "id": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "contractId": "110e8400-e29b-41d4-a716-446655440009",
    "contractDisplayNumber": "CON-1234",
    "responsiblePartyId": "dd5c2a40-9166-490d-9ed5-b5cb590a5944",
    "startDate": "2026-05-01",
    "endDate": null
  }
}

`contract.responsible_party.deleted`

Fires when a contract's responsible party is deleted. Carries the same payload shape as contract.responsible_party.updated.

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "contract.responsible_party.deleted",
  "data": {
    "id": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5",
    "contractId": "110e8400-e29b-41d4-a716-446655440009",
    "contractDisplayNumber": "CON-1234",
    "responsiblePartyId": "dd5c2a40-9166-490d-9ed5-b5cb590a5944",
    "startDate": "2026-05-01",
    "endDate": "2026-08-01"
  }
}

`hierarchy.producer.added`

Fires when a producer is newly placed under an upline in a hierarchy. Derived from a contract assignment change. The upline and commission values reflect the new placement — there is no prior-value diff.

Field	Type	Description
`contractAssignmentChangeId`	UUID	The contract assignment change that drove this hierarchy event
`contractAssignmentId`	UUID	The contract assignment the producer holds in the hierarchy
`contractId`	UUID	The contract the assignment belongs to
`personId`	UUID	The individual producer whose placement changed
`personNpn`	String	The producer's NPN
`firmId`	UUID	The firm the producer is contracted under, if any
`firmNpn`	String	The firm's NPN, if any
`agencyOrganizationId`	UUID	The agency organization the contract is sent from
`carrierOrganizationId`	UUID	The carrier organization the contract is sent to
`productId`	UUID	The carrier product the producer is contracted for
`writingNumber`	String	The writing number of the producer's contract assignment
`uplineContractAssignmentId`	UUID	The upline contract assignment the producer is placed under
`uplineNpn`	String	NPN of the upline producer
`uplineFirmId`	UUID	The upline firm, if any
`uplineFirmNpn`	String	NPN of the upline firm, if any
`uplineContractAssignmentChange`	Object	Curated upline identity (`id`, `displayNumber`, `firmName`, `personName`), if the placement has an upline
`commissionLevelId`	UUID	The producer's commission level
`commissionLevelName`	String	Name of the producer's commission level
`assignmentStatusName`	String	Name of the producer's assignment status
`effectiveDate`	Date	Effective date of the placement
`createdAt`	Date-Time	When the underlying change was created
`updatedAt`	Date-Time	When the underlying change was last updated

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "hierarchy.producer.added",
  "data": {
    "contractAssignmentChangeId": "550e8400-e29b-41d4-a716-446655440000",
    "contractAssignmentId": "660e8400-e29b-41d4-a716-446655440001",
    "contractId": "110e8400-e29b-41d4-a716-446655440009",
    "personId": "990e8400-e29b-41d4-a716-446655440004",
    "personNpn": "1234567",
    "agencyOrganizationId": "770e8400-e29b-41d4-a716-446655440002",
    "carrierOrganizationId": "880e8400-e29b-41d4-a716-446655440003",
    "productId": "aa0e8400-e29b-41d4-a716-446655440005",
    "uplineContractAssignmentId": "dd0e8400-e29b-41d4-a716-446655440007",
    "uplineNpn": "7654321",
    "uplineContractAssignmentChange": {
      "id": "cc0e8400-e29b-41d4-a716-446655440008",
      "displayNumber": "CAC-00009",
      "firmName": "Upline Agency LLC",
      "personName": "Jane Doe"
    },
    "commissionLevelId": "ee0e8400-e29b-41d4-a716-446655440010",
    "commissionLevelName": "Level A",
    "assignmentStatusName": "Active",
    "effectiveDate": "2026-06-18",
    "createdAt": "2026-06-18T09:15:00Z",
    "updatedAt": "2026-06-18T09:15:00Z"
  }
}

`hierarchy.producer.changed`

Fires when an existing producer's hierarchy position changes — its upline and/or commission level. Shares the hierarchy.producer.added payload, plus a changedFields array listing which dimensions changed. The values reflect the new placement — there is no prior-value diff.

Field	Type	Description
(all fields from `hierarchy.producer.added`)
`changedFields`	String	The hierarchy dimensions this change affected (`upline`, `commissionLevel`). Present only on `hierarchy.producer.changed`

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "hierarchy.producer.changed",
  "data": {
    "contractAssignmentChangeId": "550e8400-e29b-41d4-a716-446655440000",
    "contractAssignmentId": "660e8400-e29b-41d4-a716-446655440001",
    "contractId": "110e8400-e29b-41d4-a716-446655440009",
    "personId": "990e8400-e29b-41d4-a716-446655440004",
    "personNpn": "1234567",
    "agencyOrganizationId": "770e8400-e29b-41d4-a716-446655440002",
    "carrierOrganizationId": "880e8400-e29b-41d4-a716-446655440003",
    "productId": "aa0e8400-e29b-41d4-a716-446655440005",
    "uplineContractAssignmentId": "dd0e8400-e29b-41d4-a716-446655440007",
    "uplineNpn": "7654321",
    "commissionLevelId": "ee0e8400-e29b-41d4-a716-446655440010",
    "commissionLevelName": "Level B",
    "assignmentStatusName": "Active",
    "effectiveDate": "2026-06-20",
    "changedFields": ["upline", "commissionLevel"],
    "createdAt": "2026-06-18T09:15:00Z",
    "updatedAt": "2026-06-20T14:45:00Z"
  }
}

`hierarchy.producer.relationship.terminated`

Fires when a producer's hierarchy relationship ends — its contract assignment transitions into a terminal status. The values reflect the placement as it existed when the relationship ended.

Field	Type	Description
`contractAssignmentId`	UUID	The contract assignment whose hierarchy relationship ended
`contractId`	UUID	The contract the assignment belongs to
`personId`	UUID	The individual producer whose relationship ended
`personNpn`	String	The producer's NPN
`firmId`	UUID	The firm the producer is contracted under, if any
`firmNpn`	String	The firm's NPN, if any
`agencyOrganizationId`	UUID	The agency organization the contract is sent from
`carrierOrganizationId`	UUID	The carrier organization the contract is sent to
`productId`	UUID	The carrier product the producer is contracted for
`writingNumber`	String	The writing number of the producer's contract assignment
`uplineContractAssignmentId`	UUID	The upline contract assignment the producer was placed under
`uplineNpn`	String	NPN of the upline producer
`uplineFirmId`	UUID	The upline firm, if any
`uplineFirmNpn`	String	NPN of the upline firm, if any
`uplineContractAssignment`	Object	Curated upline identity (`id`, `displayNumber`, `firmName`, `personName`), if the placement had an upline
`commissionLevelId`	UUID	The producer's commission level
`commissionLevelName`	String	Name of the producer's commission level
`terminationReason`	String	The name of the terminal assignment status (e.g. `Terminated`, `Expired`, `Declined`, `Withdrawn`, `Transferred`, `Released`)
`terminationDate`	Date	The date the relationship ended
`createdAt`	Date-Time	When the contract assignment was created
`updatedAt`	Date-Time	When the contract assignment was last updated

{
  "id": "whe_01je7babqteg8v9p30k8zpg3ga",
  "type": "hierarchy.producer.relationship.terminated",
  "data": {
    "contractAssignmentId": "660e8400-e29b-41d4-a716-446655440001",
    "contractId": "110e8400-e29b-41d4-a716-446655440009",
    "personId": "990e8400-e29b-41d4-a716-446655440004",
    "personNpn": "1234567",
    "agencyOrganizationId": "770e8400-e29b-41d4-a716-446655440002",
    "carrierOrganizationId": "880e8400-e29b-41d4-a716-446655440003",
    "productId": "aa0e8400-e29b-41d4-a716-446655440005",
    "uplineContractAssignmentId": "dd0e8400-e29b-41d4-a716-446655440007",
    "uplineNpn": "7654321",
    "uplineContractAssignment": {
      "id": "dd0e8400-e29b-41d4-a716-446655440007",
      "displayNumber": "CA-00009",
      "firmName": "Upline Agency LLC",
      "personName": "Jane Doe"
    },
    "commissionLevelId": "ee0e8400-e29b-41d4-a716-446655440010",
    "commissionLevelName": "Level A",
    "terminationReason": "Terminated",
    "terminationDate": "2026-07-01",
    "createdAt": "2026-06-18T09:15:00Z",
    "updatedAt": "2026-07-01T14:45:00Z"
  }
}

Subscribing to Events

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.
Expect callbacks for change events — change-type events (e.g. contract.assignment_change.updated) include the new state in the payload but not the previous state. To reconstruct a full before/after diff, call GET /v1/contractAssignmentChanges/{contractAssignmentChangeId} to retrieve the previous values. Design your event processing to accommodate this additional request.