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 guide.

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

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:

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)

{
    "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"
}

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 for setup instructions.