Rest endpoints

The Webhooks REST API is not required to create a complete Webhooks solution. The REST API allows for automated management of your Webhooks. Most operations listed here can be done manually from the Developer Dashboard.

Connecting

All API access is over HTTPS, and endpoints are relative to the root URL:

https://api.layer.com

Authentication

Every request to the REST API needs to be authenticated by passing a token generated from the Developer Dashboard. The token can be revoked at any time by deleting it from the dashboard.

The Authorization header of each HTTP request should be “Bearer” followed by your token:

Authorization: Bearer <TOKEN>

If the token is missing or invalid, the request will be rejected with a 401 (Unauthorized) status code.

Content format

All REST API requests must include an Accept header specifying the Layer Webhooks content type and API version:

Accept: application/vnd.layer.webhooks+json; version=3.0

A request with any other Accept header will be rejected with a 406 (Not Acceptable) status code.

In addition, POST requests to the REST API must include the following header:

Content-Type: application/json

All responses from the REST API will include the header

Content-Type: application/json

Errors

There are a number of reasons why you might get an error response from the Webhooks REST API. These may include:

Error responses will always have either a 4xx or 5xx HTTP status code, and the body will contain a JSON object with the following properties:

Name Type Description
code int Numeric error code such as 104
id string Error identifier such as missing_property or invalid_app_id
message string Human-readable description of the error
url string Link to documentation for more info
data object (optional) Details of what caused the error, such as "property": "target_url"

An example error might look like this:

422 (Unprocessable entity)

{
  "code": 104,
  "id": "missing_property",
  "message": "The target_url property cannot be omitted.",
  "url": "http://docs.layer.com/reference/webhooks#register",
  "data: {
    "property": "target_url"
  }
}
Method HTTP request Description
Register POST /apps/:app_uuid/webhooks Register a new webhook
Verify GET https: //yourserver.com/webhook-endpoint?verification_challenge=abcxyz Request to verify your endpoint and setup
List GET /apps/:app_uuid/webhooks Get all registered webhooks
Get details GET /apps/:app_uuid/webhooks/:webhook_uuid Get details and status of a single webhook
Activate POST /apps/:app_uuid/webhooks/:webhook_uuid/activate Start verification flow to activate webhook
Deactivate POST /apps/:app_uuid/webhooks/:webhook_uuid/deactivate Deactivate a webhook
Delete DELETE /apps/:app_uuid/webhooks/:webhook_uuid Deactivate and remove a webhook

Register

Registers a new webhook with Layer’s Services, initiating the Webhook Validation process

Parameters:

Name Type Description
app_uuid string Your Layer App ID
version string Version of the Layer Webhooks protocol to use
target_url string URL to send notifications to (must be HTTPS)
events string[] Event types to receive notifications for
secret string An arbitrary string used to generate a hash of each payload to validate its content
config object Arbitrary key-value set that will be echoed back in each webhook notification

HTTP request:

POST/apps/:app_uuid/webhooks

Example:

{
    "version": "3.0",
    "target_url": "https://mydomain.com/my-webhook-endpoint",
    "events": [
        "Conversation.created",
        "Message.created"
    ],
    "secret": "1697f925ec7b1697f925ec7b",
    "config": {
        "key1": "value1",
        "key2": "value2"
    }
}
curl -X POST \
     -H 'Accept: application/vnd.layer.webhooks+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/webhooks\
 -d '{"version":"3.0","target_url":"https://mydomain.com/my-webhook-endpoint","events":["Conversation.created","Message.created"],"secret":"1697f925ec7b1697f925ec7b","config":{"key1":"value1","key2":"value2"}}'

Possible responses:

Webhook created successfully | Status: 201 (Created)

Webhook

Discussion

Newly-created webhooks will have their status set to “unverified”. You must verify the webhook (see below) before we will send events.

Secret

The secret you provide helps secure your endpoint from unauthorized access. Generate an arbitrary string, and provide it to Layer when creating the webhook. That secret can then be used for validating all data sent via the webhook to your server. This is explained in more detail above.

Please do not use a guessable string such as “secret”. Your secret should also not be visible in public spaces, such as a public Github repository.

Verify

Parameters:

This method takes no parameters.

HTTP request:

GEThttps://yourserver.com/webhook-endpoint?verification_challenge=abcxyz

Example:

curl -X GET https://yourserver.com/webhook-endpoint?verification_challenge=abcxyz

Possible responses:

Acceptable response | Status: 200 (OK)

"abcxyz"

Discussion

Once you have created a Webhook, we will send a verification request to confirm that things are set up correctly. This helps avoid leaking your information to unintended recipients.

The verification requset will be a GET request to your configured endpoint with a ?verification_challenge=RANDOM_STRING query string. Your service should respond with a status of 200 (OK) and echo back the random string in the response body. Any Content-Type can be used in your response. Once we receive a valid response, the endpoint will have its status set to “active”, and we will start sending event notifications to that endpoint.

Layer’s Servers will not attempt to retry the verification request. If verification fails (if your response doesn’t satisfy the conditions above), the status will be set as “inactive”.

List

Parameters:

Name Type Description
app_uuid string Your Layer App ID

HTTP request:

GET/apps/:app_uuid/webhooks

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer.webhooks+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/webhooks

Possible responses:

Got webhooks successfully | Status: 200 (OK)

[
    Webhook,
    Webhook
]

Get details

Parameters:

This method takes no parameters.

HTTP request:

GET/apps/:app_uuid/webhooks/:webhook_uuid

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer.webhooks+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/webhooks/<webhook_uuid>

Possible responses:

Got webhook details | Status: 200 (OK)

Webhook

Activate

If a webhook status is “inactive”, you can use this API to request reactivation. Calling this endpoint sets the webook “status” to <q"unverified" and triggers verification.

Parameters:

This method takes no parameters.

HTTP request:

POST/apps/:app_uuid/webhooks/:webhook_uuid/activate

Example:

curl -X POST \
     -H 'Accept: application/vnd.layer.webhooks+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/webhooks/<webhook_uuid>/activate

Possible responses:

Activation requested | Status: 200 (OK)

Webhook

Deactivate

If you want to pause activity to a webhook, you can deactivate it and reactivate later. The status property will be changed to inactive.

Parameters:

This method takes no parameters.

HTTP request:

POST/apps/:app_uuid/webhooks/:webhook_uuid/deactivate

Example:

curl -X POST \
     -H 'Accept: application/vnd.layer.webhooks+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/webhooks/<webhook_uuid>/deactivate

Possible responses:

Deactivated successfully | Status: 200 (OK)

Webhook

Delete

Parameters:

This method takes no parameters.

HTTP request:

DELETE/apps/:app_uuid/webhooks/:webhook_uuid

Example:

curl -X DELETE \
     -H 'Accept: application/vnd.layer.webhooks+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/webhooks/<webhook_uuid>

Possible responses:

Deleted successfully
Status: 204 (No Content)
(Empty body)