URL Endpoint Validation

For a subscription to receive events it has to be both enabled and validated.

The objective of the validation is for the end user to prove that they have access to the events we will send to the URL endpoint. Otherwise, a malicious user could provide us with a valid URL endpoint, that accepts POST requests and returns the expected 2xx status to our requests but that is not associated with the user who created the subscription. In such a scenario we would be sending unsolicited requests to this URL, potentially creating a denial of service.

The validation part can take any of two forms: one synchronous and one asynchronous.

Synchronous Validation

In our special PING events the system will include the validation_code field for non-validated subscriptions and we will read the response body trying to parse this structure:

    {"validation_code": "<validation_code>"}

Where <validation_code> must be the code we included in our PING event.

Asynchronous Validation

Requiring users to implement this behavior in their endpoints could be too much of a burden or they could not even be able to accomplish it if the endpoint service is provided by a third party. In such scenarios we also provide an alternative asynchronous validation scheme where end users need to perform a GET request to the validate endpoint. If everything is fine, then an "OK" response will be returned and the subscription will be set as validated.