Set Up a Webhook Destination

Webhooks allow you to subscribe to specific events or multiple events within a single 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

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:

JSON

{
    "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.