Webhooks

The webhooks API lets you build your own integrations that subscribe to activities in LaunchDarkly. When you generate an activity in LaunchDarkly, such as when you change a flag or you create a project, LaunchDarkly sends an HTTP POST payload to the webhook's URL. Use webhooks to update external issue trackers, update support tickets, notify customers of new feature rollouts, and more.

Designating the payload

The webhook payload is identical to an Audit log entry.

Here's a sample payload:

Webhook delivery order

Webhooks may not be delivered in chronological order. We recommend using the payload's "date" field as a timestamp to reorder webhooks as they are received.

{
  "_links": {
    "canonical": {
      "href": "/api/v2/projects/alexis/environments/test",
      "type": "application/json"
    },
    "parent": {
      "href": "/api/v2/auditlog",
      "type": "application/json"
    },
    "self": {
      "href": "/api/v2/auditlog/57c0a8e29969090743529965",
      "type": "application/json"
    },
    "site": {
      "href": "/settings#/projects",
      "type": "text/html"
    }
  },
  "_id": "57c0a8e29969090743529965",
  "date": 1472243938774,
  "accesses": [
    {
      "action": "updateName",
      "resource": "proj/alexis:env/test"
    }
  ],
  "kind": "environment",
  "name": "Testing",
  "description": "- Changed the name from ~~Test~~ to *Testing*",
  "member": {
    "_links": {
      "parent": {
        "href": "/internal/account/members",
        "type": "application/json"
      },
      "self": {
        "href": "/internal/account/members/548f6741c1efad40031b18ae",
        "type": "application/json"
      }
    },
    "_id": "548f6741c1efad40031b18ae",
    "email": "refapp@launchdarkly.com",
    "firstName": "Reese",
    "lastName": "Applebaum"
  },
  "titleVerb": "changed the name of",
  "title": "[Reese Applebaum](mailto:refapp@launchdarkly.com) changed the name of [Testing](https://app.launchdarkly.com/settings#/projects)",
  "target": {
    "_links": {
      "canonical": {
        "href": "/api/v2/projects/alexis/environments/test",
        "type": "application/json"
      },
      "site": {
        "href": "/settings#/projects",
        "type": "text/html"
      }
    },
    "name": "Testing",
    "resources": ["proj/alexis:env/test"]
  }
}

Signing the webhook

Optionally, you can define a secret when you create a webhook. If you define the secret, the webhook POST request will include an X-LD-Signature header, whose value will contain an HMAC SHA256 hex digest of the webhook payload, using the secret as the key.

Compute the signature of the payload using the same shared secret in your code to verify that the webhook was triggered by LaunchDarkly.

Understanding connection retries

If LaunchDarkly receives a non-2xx response to a webhook POST, it will retry the delivery one time. Webhook delivery is not guaranteed. If you build an integration on webhooks, make sure it is tolerant of delivery failures.

List webhooks

Fetch a list of all webhooks.

Request
Security:
ApiKey (readwrite)
Responses
200Webhooks response
401Invalid access token
403Forbidden
429Rate limited
get/api/v2/webhooks
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/webhooks \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "_links": {
    },
  • "items": [
    ]
}

Creates a webhook

Create a new webhook

Request
Security:
ApiKey (readwrite)
Request Body schema: application/json
name
string

A human-readable name for your webhook

url
required
string

The URL of the remote webhook

secret
string

If sign is true, and the secret attribute is omitted, LaunchDarkly automatically generates a secret for you.

Array of objects (StatementPostList)
sign
required
boolean

If sign is false, the webhook does not include a signature header, and the secret can be omitted.

on
required
boolean

Whether or not this webhook is enabled.

tags
Array of strings

List of tags for this webhook

Responses
200Webhook response
400Invalid request body
401Invalid access token
403Forbidden
429Rate limited
post/api/v2/webhooks
Request samples
application/json
{
  • "name": "Example hook",
  • "secret": "frobozz",
  • "statements": [
    ],
  • "sign": true,
  • "on": true,
  • "tags": [ ]
}
Response samples
application/json
{
  • "_links": {
    },
  • "_id": "57be1db38b75bf0772d11384",
  • "name": "Example hook",
  • "secret": "frobozz",
  • "statements": [
    ],
  • "on": true,
  • "tags": [ ],
  • "_access": {
    }
}

Get webhook

Get a single webhook by ID.

Request
Security:
ApiKey (readwrite)
path Parameters
id
required
string <string>

The ID of the webhook

Responses
200Webhook response
401Invalid access token
403Forbidden
404Invalid resource identifier
429Rate limited
get/api/v2/webhooks/{id}
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/webhooks/:id \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "_links": {
    },
  • "_id": "57be1db38b75bf0772d11384",
  • "name": "Example hook",
  • "secret": "frobozz",
  • "statements": [
    ],
  • "on": true,
  • "tags": [ ],
  • "_access": {
    }
}

Update webhook

Update a webhook's settings. The request should be a valid JSON Patch document describing the changes to be made to the webhook.

Request
Security:
ApiKey (readwrite)
path Parameters
id
required
string <string>

The ID of the webhook to update

Request Body schema: application/json
Array
op
required
string

The type of operation to perform

path
required
string

A JSON Pointer string specifying the part of the document to operate on

value
required
any

A JSON value used in "add", "replace", and "test" operations

Responses
200Webhook response
400Invalid request body
401Invalid access token
403Forbidden
404Invalid resource identifier
429Rate limited
patch/api/v2/webhooks/{id}
Request samples
application/json
{ }
Response samples
application/json
{
  • "_links": {
    },
  • "_id": "57be1db38b75bf0772d11384",
  • "name": "Example hook",
  • "secret": "frobozz",
  • "statements": [
    ],
  • "on": true,
  • "tags": [ ],
  • "_access": {
    }
}

Delete webhook

Delete a webhook by ID.

Request
Security:
ApiKey (readwrite)
path Parameters
id
required
string <string>

The ID of the webhook to delete

Responses
204Action completed successfully
401Invalid access token
403Forbidden
404Invalid resource identifier
429Rate limited
delete/api/v2/webhooks/{id}
Request samples
curl -i -X DELETE \
  https://app.launchdarkly.com/api/v2/webhooks/:id \
  -H 'Authorization: YOUR_API_KEY_HERE'