Skip to content

    Subscribe to webhooks

    This section explains how to subscribe to Relay webhooks.

    Create request

    To configure your webhook, you must send the Notification Service's CreateRequest.


    That request will:

    • define the events you want to subscribe to (your subscriptions). Find a list of possible events you can subscribe to here.

    • send the webhook URL to us - we will register that URL and send our response to it.

    • if successful, you will receive the notification_configuration_id with our response.

    You'll use the notification_configuration_id in all future requests for that webhook.


    The Notification Service'sCreateRequest requires three mandatory parameters:

    • request_id (type: string, format: alphanumeric)

    The request_id can be defined by you. You should use it for your internal reference - so you want to make sure it is a unique value. The request_id ensures idempotency of your calls.

    • events (type: string (repeated string))

    The events field defines the events you want to subscribe to.

    The field value can be repeated zero or more times. The order of the repeated values will be preserved.

    You can subscribe to multiple events with one webhook by adding repeated strings to the type field, such as:

    Payment.Charge.Completed.Event.v1 Payment.Charge.Failed.Event.v1

    and so on.

    You can find the accepted values (the list of all events) here.

    • webhook_configuration_data

    The webhook_configuration_data field is webhook specific. You would need a different field if you decide to use a channel other than webhooks. The expected value is your webhook URL - the URL we'll send the notifications to:


    WebhookConfigurationData {
      url = {YOUR_WEBHOOK_URL}

    Response to the Create request


    If successful, the response to your CreateRequest contains the




    Let's assume you want to set up a webhook so you get notifications whenever a payment has been charged.

    As mentioned above, you freely choose a value for the request_id field, for instance something like this:


    According to the webhook event table the corresponding event value would be


    The final field - since we are using webhooks - is the webhook_configuration_data where you put the webhook URL you've had created in the first step Create your webhook URL.

    Once that webhook is set up accordingly, you can expect incoming webhook notifications.

    Before you start parsing the data from the webhook's payload, you SHOULD verify your incoming webook notification, as shown in the next step.

    Next: verify incoming webhooks