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"
  }
}

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"
}

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“.