Set Up a Webhook Destination

To receive webhooks for all events across the Layer1 platform, you need to set up at least one webhook destination. This feature allows you to subscribe to specific events or multiple events within a single destination.

All possible webhook events that can be sent to your destination are documented in the Webhookssection of the guides, which aslo contains the guide for validating those webhooks.

In this page of the guide, we will be using the Create a new destination API. This is a POST request that will create a destination address that all webhooks of a certain subscribed event will be sent to.

Request Breakdown

The details to be sent in this request are detailed below:

Parameter	Type	Required	Description
url	String	Yes	The endpoint URL where the webhook notifications will be sent.
type	String	Yes	The type of the webhook destination [ `WEB`only at this stage].
event	String[]	Yes	An array of events to subscribe to that will trigger the webhook [`layer1:trade:conversion:created`, `layer1:trade:conversion:state-changed`, `layer1:trade:venue:address:created`, `layer1:trade:venue:withdrawal:created`, `layer1:trade:venue:withdrawal:state-changed`, `layer1:digital:address:created`, `layer1:digital:deposit:status-change`, `layer1:digital:withdrawal:status-change`, `layer1:digital:consolidation:status-change`, `layer1:digital:balance:updated` ].

Within the event array, the following events that are subscribable are listed below:

layer1:trade:conversion:created: Triggered when a new trade conversion is created.
layer1:trade:conversion:state-changed: Triggered when the state of a trade conversion changes.
layer1:trade:venue:address:created: Triggered when a new address is created at a trading venue.
layer1:trade:venue:withdrawal:created: Triggered when a new withdrawal is created at a trading venue.
layer1:trade:venue:withdrawal:state-changed: Triggered when the state of a withdrawal changes at a trading venue.
layer1:digital:address:created: Triggered when a new address is created.
layer1:digital:deposit:status-change: Triggered when the status of a deposit changes.
layer1:digital:withdrawal:status-change: Triggered when the status of a withdrawal changes.
layer1:digital:consolidation:status-change: Triggered when the status of a consolidation changes.
layer1:digital:balance:updated: Triggered when the balance is updated.

You can add any number of these events to a destination, and create as many destinations as you need to.

Example Request

Here is how an example request might look:

curl --location 'https://api.sandbox.layer1.com/digital/v1/key-pairs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbG...QQ73OA' \
--data '{
    "url": "https://webhook.site/52847769-cf41-4f94-8bec-57bfad257770",
    "type": "WEB",
    "event": [
        "layer1:trade:conversion:created",
        "layer1:trade:conversion:state-changed",
        "layer1:trade:venue:address:created",
        "layer1:trade:venue:withdrawal:created",
        "layer1:trade:venue:withdrawal:state-changed",
        "layer1:digital:address:created",
        "layer1:digital:deposit:status-change",
        "layer1:digital:withdrawal:status-change",
        "layer1:digital:consolidation:status-change",
        "layer1:digital:balance:updated"
    ]
}'

Example Response

Upon successfully submitting the request, you'll receive a response like the following:

{
    "url": "https://webhook.site/52847769-cf41-4f94-8bec-57bfad257770",
    "type": "WEB",
    "eventCodes": [
        "layer1:trade:venue:withdrawal:created",
        "layer1:digital:address:created",
        "layer1:trade:conversion:state-changed",
        "layer1:trade:venue:address:created",
        "layer1:digital:consolidation:status-change",
        "layer1:digital:deposit:status-change",
        "layer1:trade:conversion:created",
        "layer1:digital:balance:updated",
        "layer1:trade:venue:withdrawal:state-changed",
        "layer1:digital:withdrawal:status-change"
    ],
    "tenantId": "235b8540-202a-41ab-9c9b-fc74b292d9c1",
    "publicKey": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE+t4UzaqR68OQb/XnE1DjLk8AiD8bD69fbYZt+44fqRbnywMynzOZFqQWribhQDmdDc8gL6NzBODS1HtZSUIIJw=="
}

The resulting fields in the response are:

Field	Description
url	The endpoint URL where the webhook notifications will be sent, as entered in the request.
type	The type of the webhook destination, , as entered in the request.
eventCodes	An array of event codes that will trigger the webhook, as entered in the request.
tenantId	Your unique identifier of the tenant.
publicKey	The public key used for used to validate the incoming webhook at the given URL.

Please pay special attention to your publicKey when validating the webhooks sent to the URL listed.

If you need to get the publicKey again, or see what current events you are subscribed to accross multiple destinations, you can use the List destinations API. This is a GET request that retrieves the destination created on the previous page, as well as any other destination addresses associated on the account with the same tennantId.