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.

For the complete list of all possible webhook events that can be sent to your destination, see the Webhooks section of the guides. It also includes a guide on validating those webhooks.

To create a destination address to which all webhooks of a specific subscribed event will be sent, send the POST /notification/v1/destinations request with the following body parameters:

{
    "url": "https://hooks.slack.com/services/T88HSLB/B08360RN3/sh6EydWDblDf",
    "type": "SLACK",
    "events": [
        "layer1:crypto:address:created",
        "layer1:crypto:deposit:statusChange",
        "layer1:crypto:withdrawal:statusChange",
        "layer1:crypto:consolidation:statusChange",
        "layer1:notification"
    ]
}

Parameter	Type	Required	Description
`url`	String	Yes	The endpoint URL to which the webhook notifications will be sent
`type`	String	Yes	The type of the webhook destination. Available options: `WEB` (for web notifications) or `SLACK` (for the Slack messenger notifications)
`event`	String	Yes	An array of events that will trigger the webhook

Within the event array, the following events are available for subscription and triggered when:

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

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

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"
    ]
}'

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=="
}

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

🚧
Pay special attention to your publicKey when validating the webhooks sent to the listed URL.

To get the publicKey again, or see what current events you are subscribed to across multiple destinations, send the GET /hook/v1/destinations request. It retrieves the destination created on the previous page, as well as any other destination addresses associated on the account with the same tennantId.

🚧Pay special attention to your publicKey when validating the webhooks sent to the listed URL.

🚧
Pay special attention to your `publicKey` when validating the webhooks sent to the listed URL.