Skip to content

General-purpose webhook URLs

Notification pings for events that occur on an application or its environments can be sent to a general-purpose webhook URL. Notifications pings to a webhook URL can be useful for:

  • Pinging a testing service whenever a particular environment is updated. This can include page speed tests or integration testing to ensure that a checkout process is still working as expected.
  • Logging the deployment against a datastore (e.g. a Google spreadsheet).

Request header and versions

The webhook request is sent with an x-wpvip-webhook HTTP request header. The x-wpvip-webhook header value is a string indicating the version number of the webhook payload.

When breaking changes are made to the payload structure the version number will be incremented.

  • Current webhook version: v1 (e.g. x-wpvip-webhook: "v1")
  • Legacy webhook version: v0 (e.g. x-wpvip-webhook: "v0")

Request body

The service receiving the Notifications ping must be able to accept an HTTP POST. The ping is a JSON-formatted request body with the following structure:

{
  "type": "environment:code:deployed",
  "timestamp": "2024-01-26T22:16:30.000Z",
  "data": {
    "application": {
      "id": 1234,
      "name": "example-dot-com"
    },
    "branch": "develop",
    "commit": {
      "author": "example-user",
      "description": "Example commit message",
      "hash": "0abc1234e5af99deadbeefb98765432181e03b1a5b5d69"
    },
    "deploymentId": 12345678,
    "environment": {
      "domain": "develop.example.com",
      "id": 5678,
      "type": "develop"
    },
    "repo": "wpcomvip/example-dot-com"
  }
}

Note

Very infrequently, an environment might have a name value assigned to it in addition to a type. For these environments, both the type and the name keys and values will be included in the payload.

Event types

The type payload property contains a string that indicates the kind of event that occurred. The behavior of the request handler can vary depending on the event type.

Currently supported event types:

  • environment:code:deployed
  • environment:code:deploy-failed

Legacy request body (v0)

The JSON-formatted structure of the legacy (v0) request body:

{
	"domain": "PRIMARY_DOMAIN",
    "repo": "GITHUB_ORGANISATION/GITHUB_REPOSITORY",
    "branch": "REPOSITORY_BRANCH",
    "sha": "COMMIT_SHA",
    "status":"success|failed",
	"commit_author_username": "COMMIT_AUTHOR",
	"commit_message": "COMMIT_MESSAGE"
}

Note

An updated format (“v1”) for the request body of webhook URLs was released on 2 February 2024. Any remaining Destinations using the v0 legacy format will be automatically updated to v1 on 1 April 2024.

Update a v0 legacy request body to v1

Destinations for webhook URLs that were configured prior to the release of v1 will send requests with the legacy request body format (v0). Only the v1 request body is formatted to support upcoming event types. All Destinations in the legacy v0 format should be updated to v1 as soon as possible.

Handlers expecting a payload in the v0 legacy format should be updated to handle the v1 format prior to updating a Destination. To avoid possible downtime, inspect the version in the x-wpvip-webhook request header and vary the logic accordingly.

To identify Destinations currently in the v0 legacy format

  1. Navigate to the organization view of the VIP Dashboard.
  2. Select “Notifications” from the lefthand navigation menu.
  3. Select the button labeled “Manage Destinations” located in the upper right of the Notifications panel.

Destinations in the v0 format are indicated by a label with the text “Legacy”.

To update an existing Destination in the v0 legacy format to v1

  1. Select the “Edit” text link to the right of the Destination in legacy format.
  2. In the screen titled “Edit Destination”, navigate to the dropdown field labeled “Webhook Version”.
  3. Select “Current” from the dropdown options.
  4. Select the button labeled “Update Destination“.

Last updated: February 06, 2024

Relevant to

  • Node.js
  • WordPress