Introduction

The event subscription service enables users of Neo to react to various events happening in the platform. This is achieved by creating a subscription to an event through the event subscription service. You can find the list of all events using the Get event types endpoint.

Creating or updating an event subscription is a two-stepped approach. First you need to call the event subscription service to create or update the subscription to the event you are interested in. Second is to validate the event handler webhook as described below. No events will be sent to your event handler webhook until after the webhook has been successfully validated.

🚧

Note:

The event handler webhook must be running and reachable by Neo so that a successful validation can take place.

How does it work?

When you create or update a subscription to an event using the endpoint Create or Update Event Subscription, your webhook is required to participate in a validation handshake. This is necessary to prove ownership of the webhook endpoint before Neo will start delivering events to your webhook.

Once you've called the Create or Update Event Subscription endpoint, you will receive a call back to your event handler webhook (passed in the create or update event subscription endpoint as notificationUrl) with a payload looking like the following:

[
    {
        "id": "c744ddc49-d80d-43d7-ad3c-7a5b3854f810",
        "topic": "/subscriptions/253ec414-bac5-419d-bdf4-57913a9a3d0b/resourceGroups/xxxxx/providers/microsoft.eventgrid/domains/xxxx/topics/loans",
        "subject": "",
        "data": {
            "validationCode": "CFD3878B-E454-4CE3-AC15-26D726A48E1B",
            "validationUrl": "https://rp-westeurope.eventgrid.azure.net:553/eventsubscriptions/loans-6c51b3c9-656d-48e6-b613-fba582d62e2c/validate?id=CFD3878B-E454-4CE3-AC15-26D726A48E1B&t=2022-07-04T11:41:58.3861366Z&apiVersion=2020-06-01&token=OXGzjHWqbJOHYyEEI9TbYxn5PJXE16%2byGN16cEyT0as%3d"
        },
        "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
        "eventTime": "2022-07-04T11:41:58.3861366Z",
        "metadataVersion": "1",
        "dataVersion": "2"
    }
]

There are two ways of completing the validation handshake:

• Synchronous handshake: The data portion of the event (as shown above) includes a validationCode property. In order to complete the handshake synchronously, your endpoint must return an HTTP Code of 200 with the validationCode in the response. The HTTP request must finish within 30 seconds. If the validation code is not in the response body. Neo will treat the handshake as asynchronous (see below).

The returned payload should look like the following:

{
    "validationResponse": "CFD3878B-E454-4CE3-AC15-26D726A48E1B"
}

🚧

Note:

You must return an HTTP 200 OK response status code. Other codes (such as HTTP 202 Accepted) are not recognized as valid responses.
If the HTTP request does not complete within 30 seconds, the operation will be canceled and it may be reattempted after a 5 second delay.

• Asynchronous handshake: In the above-mentioned subscription validation event, the data portion also includes a validationUrl property. To complete the handshake, use this URL and do a GET request to it. This can be done manually through a web browser or in code.
  
  The validation URL is valid for 10 minutes. If you don't complete the validation within those 10 minutes, the event subscription will be marked as invalid and you will not receive any further events.
  
  This authentication mechanism requires the webhook endpoint to return an HTTP status code of 200 so that it knows that the POST for the validation event was accepted. No other HTTP status code is considered valid during this handshake process.

A successful asynchronous handshake will return the following payload:

"Webhook successfully validated as a subscription endpoint."

Upon error, the returned payload will be:

{
    "error": {
        "code": "InvalidRequest",
        "message": "Invalid URL. Please try again with a valid verification URL."
    }
}

🚧

Note:

The event subscription remains in a Pending state until it is validated.

After successfully validated your webhook, you will receive the notifications whenever the event you just subscribed to happens in the platform as shown below.

[
    {
        "id": "850fda02-f15c-4cae-b811-22a74707be16",
        "subject": "loans/c8c24405-0593-4ee2-b1ae-cc71c293e307",
        "data": {
            "LoanIdentifier": "c8c24405-0593-4ee2-b1ae-cc71c293e307",
            "PaymentIdentifier": "a5d2561b-6a13-4add-a6f4-91b6ef5f081a",
            "RequestId": "a32b5a29-79f3-491c-a843-50ef05de0c8e",
        },
        "eventType": "ExternalPaymentRegisteredEvent",
        "dataVersion": "1.0",
        "metadataVersion": "1",
        "eventTime": "2022-07-04T09:13:17.1083434Z",
        "topic": "/subscriptions/253ec414-bac5-419d-bdf4-57913a9a3d0b/resourceGroups/xxxxxx/providers/Microsoft.EventGrid/domains/xxxx/topics/loans"
    }
]