Subscribing to corporate action notifications

As soon as corporate actions are announced on the market, we provide the corresponding notification. This also includes any subsequent update events that become known through new information about this event.

To receive such notifications about corporate actions, you only have to subscribe to webhooks with the corresponding event type CORPORATE_ACTION.

Read our guide to learn more about webhooks registration.

Once you are registered, you will receive webhooks for corporate actions in which you or your users are involved.

Process flow

The following diagram illustrates the process flow of a corporate action notification:

Corporate action notification flow

Notifications structure

Basically, the structure of the notifications is the same for all types of corporate actions:

A unique corporate action ID, which is assigned in each case and propagated throughout our system. Corporate action IDs will be visible in the transactions reporting to link notifications with the associated cash or security impact.
General information about the instrument and nature of the corporate action.
Information about how the corporate action is processed (options and movements).
Occasional additional information (if available) containing explanatory notes, text fields, or similar data that issuers consider relevant to the context of a corporate action.

Example notification

The following example is a corporate action notification for cash dividends.

{
    "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",
        "instrument":
        {
            "uuid": "48b798b7-3a62-4f30-8307-ee94d35b21b7",
            "isin": "FR0010524777",
            "name": "Lyxor MSCI New Energy ESG Filtered (DR) ETF"
        },
        "iso_type": "DVCA",
        "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",
        "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"
}

Dates

Parameter	Description
`ex_date`	The date up to which a particular share is eligible for the upcoming corporate action. (Generally, eligibility is determined by the execution of orders placed before the ex-date.) Example: If buyers purchase a share on the ex-date, they are not entitled to participate in the upcoming corporate action; but the seller still would be. (The buyers would only participate in the corporate action if the purchase transaction had taken place on ‘ex-date - 1’.)
`record_date`	Date on which the issuer reviews its records to determine its authorised shareholders. The authorised shareholders are those who are affected by the respective corporate action.
`payment_date`	Date on which the payment for a cash-based corporate action is made. In the case of corporate actions in the form of securities, the payment date is the date on which the securities are paid (e.g., securities resulting from a merger).

Announcement status

Corporate action notifications can be assigned different statuses during their lifecycle. Upvest discloses these statuses in accordance with ISO standards.

The announcement_status field provides information on the status of information known about a corporate action on the mark.

Status	Description
`COMPLETE`	The message contains full details of the corporate action at the time the event was notified. The message contains full details of the corporate action at the time the event was notified. It has also already been confirmed by the selected official source of the account service provider. Further updates to the event are still possible.
`COMPLETE_UNCONFIRMED`	The message contains full details of the corporate action event at the time of notification of the event, but the occurrence of the event has not been confirmed by the selected official source of the account service provider. Further updates to the event are still possible.
`PRELIMINARY_ANNOUNCEMENT_CONFIRMED`	The message may not contain all the details of the corporate action, but the occurrence of the event has been confirmed by the official source chosen by the account service provider.
`PRELIMINARY_ANNOUNCEMENT_UNCONFIRMED`	The message may not contain complete details of the corporate action event and the occurrence of the event has not been confirmed by the selected official source of the account service provider at the time the message is sent.