# Corporate actions webhooks

Webhooks are a mechanism for your software to automatically receive information about corporate action events. By leveraging webhooks, you remove the need to poll the API for corporate action state changes.

For general information about webhooks, refer to the [Implementing webhooks](/products/tol/getting_started/implementing_webhooks) guide.

Clients can subscribe to webhooks to track corporate action announcements, instruction submission, processing, and settlement across all eligible instruments.

When corporate actions are announced, instructions are submitted, processed, or settled, the following events are sent via webhook:

## Corporate action events

Corporate actions transition through states as they are announced, processed, and settled. All state changes are reflected through a single event type with varying status fields:

| **Event Type** | **Description** | **When Triggered** |
|  --- | --- | --- |
| `CORPORATE_ACTION.UPDATED` | A corporate action announcement, update, or settlement event has occurred. | When announcement is made; when new information becomes available; when instruction window opens; when processing/settlement occurs. |


The corporate action object contains status fields that indicate the lifecycle stage:

- **`announcement_status`** — Stage of the announcement (PRELIMINARY_ANNOUNCEMENT_CONFIRMED, ANNOUNCEMENT_CONFIRMED, AMENDMENT, DELETION)
- **`function_of_message`** — The nature of the update (NEW, UPDATE, AMENDMENT, DELETION, REVERSAL)
- **`record_date`**, **`ex_date`**, **`payment_date`** — Key dates in the corporate action lifecycle
- **`options`** — Available election choices (CASH, REINVESTMENT, SELL, etc.)
- **`movements`** — Resulting security/cash movements (populated after settlement)


### Corporate action webhook example

CORPORATE_ACTION.UPDATED - Announcement
```json
{
    "id": "d0cb44d6-d61f-4272-b0f5-a8c7349b8b9a",
    "created_at": "2024-09-05T12:03:43.201937702Z",
    "type": "CORPORATE_ACTION.UPDATED",
    "object": {
        "id": "b96b1ee7-d491-43eb-b5e4-4833af9c9c2f",
        "corporate_action_reference": "DEDVCA0000000000",
        "instrument": {
            "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7",
            "isin": "FR0010524777",
            "name": "Lyxor MSCI New Energy ESG Filtered (DR) ETF"
        },
        "name": "CASH_DIVIDEND",
        "iso_type": "DVCA",
        "currency_denomination": "EUR",
        "mandatory_voluntary_indicator": "MANDATORY",
        "announcement_status": "PRELIMINARY_ANNOUNCEMENT_CONFIRMED",
        "function_of_message": "NEW",
        "announcement_date": "2023-11-09",
        "ex_date": "2023-12-04",
        "record_date": "2023-12-05",
        "effective_date": "2023-12-10",
        "options": [
            {
                "option_number": "001",
                "option_type": "CASH",
                "option_details": {
                    "default_option": "TRUE"
                },
                "movements": [
                    {
                        "movement_type": "CASH",
                        "movement_details": {
                            "credit_debit_indicator": "CREDIT",
                            "payment_date": "2023-12-10",
                            "gross_dividend": "0.54",
                            "withholding_tax": "0.30",
                            "currency": "EUR"
                        }
                    }
                ]
            }
        ]
    },
    "webhook_id": "dbebe0ac-a407-4d43-a404-b8fe846eb691"
}
```

CORPORATE_ACTION.UPDATED - Instruction confirmed
When an instruction is submitted and confirmed, you receive an updated event with the `function_of_message` field reflecting the confirmation. The object includes the instruction details.

CORPORATE_ACTION.UPDATED - Settlement
When settlement occurs (on the payment date), movements populate the `movements` array showing resulting security and cash positions.

## Recommended workflow

To implement corporate action tracking with webhooks:

1. **Subscribe to corporate action events** — Listen for all `CORPORATE_ACTION.UPDATED` events
2. **Monitor announcement stage** — When `function_of_message` is `NEW`, a new corporate action is announced
3. **Track instruction window** — When instruction options become available (`options` array is populated), users can submit instructions
4. **Confirm instruction submission** — Monitor webhooks for instruction confirmation (`function_of_message` = UPDATE or AMENDMENT with your instruction reflected)
5. **Monitor settlement** — When `movements` array is populated, settlement has occurred and positions are updated
6. **Set up error handling** — Implement retry logic for webhook delivery failures


See [implementing webhooks](/products/tol/getting_started/implementing_webhooks) for setup instructions.