--- title: "Contracting API: Webhook Events" description: "The Contracting API publishes webhook events when contracts and contract assignments change. Use these events to keep downstream systems synchronized without polling." url: "https://developer.agentsync.io/contracting-api-webhooks" image: "https://developer.agentsync.io/_og/d/c_Ocean.takumi,title_~Q29udHJhY3RpbmcgQVBJOiBXZWJob29rIEV2ZW50cw,description_The+Contracting+API+publishes+webhook+events+when+contracts+and+contract+assignments+change.+Use+these+events+to+keep+downstream+systems+synchronized+without+polling.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMxODdFRkYifX19,p_Ii9jb250cmFjdGluZy1hcGktd2ViaG9va3Mi,s_oxE3xz4KQjzQrtye.png" --- # 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](https://developer.agentsync.io/webhooks-quick-start-guide). ## [Available Events](#available-events) ### [Contracting Events](#contracting-events) | Event Type | When It Fires | Common Use Cases | | :----------------------------------------- | :------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | | contract.updated | A contract record is created or updated | Mirror contract state downstream | | contract.deleted | A contract record is deleted | Remove the contract from downstream stores; reconcile deletions | | contract.assignment.updated | A contract assignment is created or updated | Sync commission level, upline and writing numbers into payout setup | | contract.assignment.deleted | A contract assignment is deleted | Remove the assignment from downstream stores | | contract.assignment_change.updated | A contract assignment change (workflow task) is created or updated | Drive workflow queues; track pending contracting tasks and status transitions | | contract.assignment_change.deleted | A contract assignment change is deleted | Clear resolved tasks out of your workflow queue | | contract.packet.submitted | A contract packet is submitted | Notify onboarding teams; start downstream review; track submission SLAs | | contract.producer_status.updated | A producer's status within an organization is created or updated | Gate producer access on active status; keep organization rosters current | | contract.responsible_party.updated | A contract's responsible party is created or updated | Route contracting correspondence; keep escalation contacts current | | contract.responsible_party.deleted | A contract's responsible party is deleted | Drop stale contacts from routing and escalation rules | | hierarchy.producer.added | A producer is newly placed under an upline in a hierarchy | Build or refresh your org hierarchy; open a commission payout path | | hierarchy.producer.changed | An existing producer's hierarchy position (upline and/or commission level) changes | Recalculate downline rollups; adjust commission splits (see changedFields) | | hierarchy.producer.relationship.terminated | A producer's hierarchy relationship ends — its contract assignment transitions into a terminal status | Close out payout paths; drop the producer from active downline reporting | ### [Identity Events](#identity-events) Producer identity events (`id.producer.*`) are published by the Identity API, not the Contracting API. See [Identity API Webhook Events](https://developer.agentsync.io/identity-api-webhooks) for the full event catalog and payload schemas. ## [Event Schema](#event-schema) All Contracting API webhook events share the same envelope: ```json { "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](#example-payloads) ### [`contract.updated`](#contractupdated) 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. ```json { "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`](#contractdeleted) 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 | ```json { "id": "whe_01je7babqteg8v9p30k8zpg3ga", "type": "contract.deleted", "data": { "contractId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5" } } ``` --- ### [`contract.assignment.updated`](#contractassignmentupdated) 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 annualization options embedded in `GET /v2/assigned-products` describe the same concept in a different shape, so treat the event value as months rather than expecting a direct field match. > **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. ```json { "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`](#contractassignmentdeleted) 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 | ```json { "id": "whe_01je7babqteg8v9p30k8zpg3ga", "type": "contract.assignment.deleted", "data": { "contractAssignmentId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5", "displayNumber": "CA-1234" } } ``` --- ### [`contract.assignment_change.updated`](#contractassignment_changeupdated) 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)](#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: ```text GET /v2/contract-assignment-changes/{contractAssignmentChangeId} ``` The response is the change record itself — its `assignmentStatus*` fields are the change's own status, and `snapshotStartOn`/`snapshotEndOn` give the window during which it represented the assignment's state. List prior changes for the same `contractAssignmentId` to reconstruct the full before/after picture alongside the `new*` fields in the webhook payload. 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 | ```json { "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`](#contractassignment_changedeleted) 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 | ```json { "id": "whe_01je7babqteg8v9p30k8zpg3ga", "type": "contract.assignment_change.deleted", "data": { "contractAssignmentChangeId": "2ba59c5c-1690-49e7-8ee7-69aec9c0cdf5", "displayNumber": "CAC-1234" } } ``` --- ### [`contract.packet.submitted`](#contractpacketsubmitted) 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 | ```json { "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`](#contractproducer_statusupdated) 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 | ```json { "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`](#contractresponsible_partyupdated) > 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 | ```json { "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`](#contractresponsible_partydeleted) > Fires when a contract's responsible party is deleted. Carries the same payload shape as `contract.responsible_party.updated`. ```json { "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`](#hierarchyproduceradded) > 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 | ```json { "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`](#hierarchyproducerchanged) > 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. > **`personId` is always present in these events, including for firms.** This differs from the REST hierarchy node, where a `FIRM` position has `personId: null`. To tell a firm from an individual in an event payload, test `firmId` for presence rather than `personId` for null — the latter is never null here, so it will classify every firm as an individual. See [Hierarchy Nodes](https://developer.agentsync.io/contracting-api-overview#hierarchy-nodes). | 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 | ```json { "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`](#hierarchyproducerrelationshipterminated) > 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 | ```json { "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](#subscribing-to-events) When registering your endpoint in the webhook portal, subscribe to the `contract` high-level event group to receive all contracting events (and `hierarchy` for hierarchy events), or subscribe to specific event types if you only need a subset. To receive producer identity events, subscribe separately — see [Identity API Webhook Events](https://developer.agentsync.io/identity-api-webhooks). See the [Webhooks Quick Start Guide](https://developer.agentsync.io/webhooks-quick-start-guide) for step-by-step registration instructions. ## [Processing Recommendations](#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](https://developer.agentsync.io/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 /v2/contract-assignment-changes/{contractAssignmentChangeId}` and list prior changes for the same assignment. Design your event processing to accommodate this additional request.