> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agency Regulatory Action Updated
> Webhook event triggered when NIPR amends a regulatory action already on file against an agency
## Overview
The `DOWNSTREAM_ENTITY_REGULATORY_ACTION_UPDATED` webhook is triggered when the daily NIPR PDB-alerts pass reports that a regulatory action already on file against one of your agencies has been **amended**.
Regulators revise filings routinely, and the revision is often the part that matters. The case this event was built for: an agency's Maryland action, first recorded in July, came back from a later pass with its disposition escalated to `Cease And Desist, Cease And Desist From All Insurance Activity`. The action was already on file, so no new-action event fired, and the carrier heard nothing about the escalation.
[Agency Regulatory Action Added](/guides/webhooks/downstream-entity-regulatory-action-added) tells you an action exists. This event tells you what it now says.
**Webhook type:** `DOWNSTREAM_ENTITY_REGULATORY_ACTION_UPDATED`
### Triggers
This webhook fires when the daily NIPR PDB-alerts pass changes any of the nine amendable fields on an action already stored: `originOfAction`, `reasonForAction`, `disposition`, `dateOfAction`, `effectiveDate`, `enterDate`, `fileRef`, `penaltyFineForfeitureInUSD` or `lengthOfOrderInDays`.
A field being **cleared** counts as a change, and arrives with the field listed in `changedFields` and `null` at the top level.
This webhook is sent **immediately**, with no debouncing, and there is one delivery per amended action.
## What does not fire this event
| Change | Use instead |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A regulatory action Turris has not seen before | [Agency Regulatory Action Added](/guides/webhooks/downstream-entity-regulatory-action-added) |
| A daily pass that re-reads an action without changing it | Nothing. Silent by design, see below |
| A change to `actionId`, `npn`, `stateCode` or `niprDataSubscriptionId` | Those identify the action. A different value is a different action, delivered as [Agency Regulatory Action Added](/guides/webhooks/downstream-entity-regulatory-action-added) |
| An action is removed | Not currently signalled |
| An amendment to an action against a **producer** | [Agent Regulatory Action Updated](/guides/webhooks/agent-regulatory-action-updated) |
| A licence or appointment changes the agency's compliance status | [Agency Compliance Status Change](/guides/webhooks/downstream-entity-compliance-status-change) |
| Any change to the agency's own record, such as a rename | [Agency Updated](/guides/webhooks/downstream-entity-updated) |
### A pass that changes nothing delivers nothing
The daily NIPR pass re-reads every action it already holds for you and compares it against what we have stored. When nothing has changed, nothing is written and nothing is sent. You receive an event only when one of the nine amendable fields genuinely changed value.
So the volume of this event tracks real regulator activity, not our polling schedule. Deliveries are rare and bursty rather than daily.
**Subscribe to both regulatory-action events, or neither.** Webhook subscriptions are per event type. If you take
only this one, you hear about revisions to actions you were never told about in the first place.
## Payload Example
A disposition escalating from a suspension to a cease-and-desist:
```json theme={null} theme={null}
{
"webhookType": "DOWNSTREAM_ENTITY_REGULATORY_ACTION_UPDATED",
"upstreamEntityId": "507f1f77bcf86cd799439010",
"payload": {
"regulatoryActionId": "507f1f77bcf86cd799439013",
"actionId": "MD-2024-007781",
"npn": "8901234",
"stateCode": "MD",
"niprDataSubscriptionId": "507f1f77bcf86cd799439014",
"originOfAction": "Regulatory Action",
"reasonForAction": "Unfair Trade Practice",
"disposition": "Cease And Desist, Cease And Desist From All Insurance Activity",
"dateOfAction": "2024-03-01T00:00:00.000Z",
"effectiveDate": "2024-03-15T00:00:00.000Z",
"enterDate": "2024-03-04T00:00:00.000Z",
"fileRef": "MD-DOI-91002",
"penaltyFineForfeitureInUSD": 25000,
"lengthOfOrderInDays": 0,
"downstreamEntityId": "507f1f77bcf86cd799439012",
"downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
"legalName": "RT Specialty LLC",
"branchName": "RT Specialty - Miami Beach, FL",
"producerCode": "RTS-4471",
"changedFields": ["disposition"],
"previousValues": {
"disposition": "License, Suspension"
}
}
}
```
Two fields amended in one pass, one of which had no prior value:
```json theme={null} theme={null}
{
"webhookType": "DOWNSTREAM_ENTITY_REGULATORY_ACTION_UPDATED",
"upstreamEntityId": "507f1f77bcf86cd799439010",
"payload": {
"regulatoryActionId": "507f1f77bcf86cd799439013",
"actionId": "MD-2024-007781",
"npn": "8901234",
"stateCode": "MD",
"niprDataSubscriptionId": "507f1f77bcf86cd799439014",
"originOfAction": "Regulatory Action",
"reasonForAction": "Unfair Trade Practice",
"disposition": "License, Revocation",
"dateOfAction": "2024-03-01T00:00:00.000Z",
"effectiveDate": "2024-04-01T00:00:00.000Z",
"enterDate": "2024-03-04T00:00:00.000Z",
"fileRef": "MD-DOI-91002",
"penaltyFineForfeitureInUSD": 25000,
"lengthOfOrderInDays": 180,
"downstreamEntityId": "507f1f77bcf86cd799439012",
"downstreamEntityAssociationId": "507f1f77bcf86cd799439011",
"legalName": "RT Specialty LLC",
"branchName": "RT Specialty - Miami Beach, FL",
"producerCode": "RTS-4471",
"changedFields": ["effectiveDate", "lengthOfOrderInDays"],
"previousValues": {
"effectiveDate": "2024-03-15T00:00:00.000Z",
"lengthOfOrderInDays": null
}
}
}
```
### Payload Fields
Every field [Agency Regulatory Action Added](/guides/webhooks/downstream-entity-regulatory-action-added) carries, in its current state after the amendment, plus the two diff fields at the end.
| Field | Type | Description |
| ------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `regulatoryActionId` | string | Turris's id for this action record. |
| `actionId` | string | NIPR's own identifier for the action. Part of the deduplication key, see below. |
| `npn` | string | The agency's National Producer Number. |
| `stateCode` | string | The state that took the action, e.g. `MD`, `TX`. |
| `niprDataSubscriptionId` | string | The NIPR data subscription this action was retrieved under. |
| `originOfAction` | string \| null | What surfaced the action, e.g. `Regulatory Action`. |
| `reasonForAction` | string \| null | Why the action was taken, e.g. `Unfair Trade Practice`. |
| `disposition` | string \| null | The outcome, e.g. `License, Revocation`. The field most amendments change. |
| `dateOfAction` | string \| null | ISO-8601. When the action was taken. |
| `effectiveDate` | string \| null | ISO-8601. When the action takes effect. |
| `enterDate` | string \| null | ISO-8601. When the action was entered into NIPR. |
| `fileRef` | string \| null | The regulator's reference for supporting documentation. |
| `penaltyFineForfeitureInUSD` | number | Monetary penalty. `0` means no penalty. |
| `lengthOfOrderInDays` | number | Duration of the order. `0` means none specified **or** indefinite; NIPR does not distinguish the two. |
| `downstreamEntityId` | string, may be absent | The agency record the action is against. |
| `downstreamEntityAssociationId` | string, may be absent | The relationship you hold with that agency. The same identifier carried by every other webhook. Match on this. |
| `legalName` | string, may be absent | The agency's legal name. |
| `branchName` | string, may be absent | Branch name of that relationship. |
| `producerCode` | string \| null, may be absent | Your producer code for the relationship. |
| `changedFields` | string\[] | Which published fields this amendment changed. Never empty. |
| `previousValues` | object \| null | The prior value of exactly the fields in `changedFields`. `null` when the prior state could not be read. |
**`previousValues` has three states and they mean different things.**
* The whole object is `null`: we could not read the prior state of the action. The current values are still correct.
Re-read from the API if you need the history.
* A key is **absent**: that field was not part of this amendment.
* A key is `null`: the field had **no value before**, so this amendment populated it.
A field the amendment **cleared** therefore shows its old value in `previousValues` and `null` at the top level.
Never read a `null` inside `previousValues` as "cleared", it is the opposite.
**The entity fields behave exactly as on the Added event.** `downstreamEntityId`,
`downstreamEntityAssociationId`, `branchName`, `legalName` and `producerCode` come from one best-effort lookup
against your relationship with the agency. Either all of them arrive or none of them do, and absent means "we could
not resolve this" rather than anything about the data.
## Deduplication
Key on `actionId` + `npn` + `stateCode`, the same key the Added event uses, so an amendment updates the record you
already hold rather than creating a second one.
The whole action is delivered rather than the diff alone, which means you can apply this event as a wholesale
overwrite of your copy and ignore `changedFields` entirely if you have no use for it.
## No fan-out across carriers
An action against an agency held by two carriers exists as two separate records, one per NIPR data subscription, so
each carrier receives exactly **one** delivery per amendment, carrying their own `downstreamEntityAssociationId`.
This differs from [Agency Updated](/guides/webhooks/downstream-entity-updated), where a single change to the agency
record fans out across every relationship you hold. There is nothing to de-duplicate across relationships here.
## Related topics
- [Agent Regulatory Action Updated](/guides/webhooks/agent-regulatory-action-updated.md)
- [Agency Regulatory Action Added](/guides/webhooks/downstream-entity-regulatory-action-added.md)
- [Webhooks Overview](/guides/webhooks.md)