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"
    ]
}
ParameterTypeRequiredDescription
urlStringYesThe endpoint URL to which the webhook notifications will be sent
typeStringYesThe type of the webhook destination. Available options: WEB (for web notifications) or SLACK (for the Slack messenger notifications)
eventStringYesAn 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=="
}
FieldDescription
urlThe endpoint URL where the webhook notifications will be sent as specified in the request
typeThe type of the webhook destination as specified in the request
eventCodesAn array of event codes that will trigger the webhook, as specified in the request
tenantIdYour unique tenant identifier
publicKeyThe 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.