API Introduction

Requirements

  • Your server must be able to receive HTTP/1.1 requests and support keep-alive requests
  • Your server needs to respond to HTTP GET requests on your webhook URL for verification
  • Your server needs to respond to HTTP POST requests on your webhook URL to acknowledge receiving notifications

Setup

Webhooks can be configured via the Developer Dashboard or the REST API.

Webhooks Concepts

Every time an event that you subscribe to happens, Layer’s servers will send an HTTP POST request to a target URL that you configure when creating the webhook. Each event type has a specific payload with relevant information about the event. The payload for each event is described in Payloads.

If your server doesn’t send an appropriate response when a webhook is triggered, we will retry the request with an exponential backoff delay for up to 30 minutes. If an appropriate response isn’t received within this time, the webhook will be marked as “inactive”. See Responding to a Webhook for details.

Note

Webhooks will only trigger when events reach the server. If a client is offline or has a poor network connection, the webhook may not trigger for a long time, even if the client makes it appear that the original action has completed.

Webhook Verification

Webhooks have three possible status values:

  • “unverified”: A newly created webhook; will not receive notifications until verified
  • “active”: A webhook that is active and notifications are being delivered
  • “inactive”: A webhook that is no longer delivering notifications

A newly-created webhook will be “unverified”. Once verified, its status changes to “active”. If your endpoint doesn’t respond to notifications, it will be changed to “inactive”.

You can check the status of your webhooks in the Developer Dashboard.

Status is changed from “unverified” or “inactive” to “active” via the Verification Process, consisting of either:

  • Registering a Webhook
    1. A webhook registration is done via REST API or Developer Dashboard
    2. A Verification request is sent to your server
    3. If correctly handled, status is changed to “active”; else its changed to “inactive”
  • Activating an “inactive” Webhook
    1. A webhook activation request is done via REST API or Developer Dashboard
    2. A Verification request is sent to your server
    3. If correctly handled, status is changed to “active”; else its changed to “inactive”