Outgoing webhooks

This feature is limited to certain plans. Please visit our pricing page to learn more.

Runway’s outgoing webhooks (available for Enterprise teams and above) give your team even more flexibility to expand upon Runway’s core features to support your team’s unique workflows and processes. You can leverage outgoing webhooks to subscribe to endpoints of your choosing, on specific events triggered by Runway.

Adding new webhook endpoints

To add, remove, or configure webhook endpoints, navigate to the “Webhooks” section of your Organization settings. Here, you’ll see a list of existing webhook endpoints, which can be modified or deleted. To add a new endpoint, simply specify the endpoint’s URL, set an optional endpoint description, and choose one or more event types that will be sent to the endpoint.

Leaving the event types field empty will automatically subscribe the webhook endpoint to all event types.

Webhook event types

Runway supports a number of key webhook event types that you can subscribe to in order to implement custom functionality for your team’s unique needs.

For a complete list of webhook event types and corresponding payloads, please visit our API reference documentation.

Debugging, testing, and verifying webhooks

To access more advanced webhook functionality including sending test events to your endpoints, viewing event history, and replaying failed messages, visit the App Portal by clicking on the link found at the bottom of the webhook settings page.

Runway has partnered with webhook provider Svix to manage the delivery of webhook messages in a secure and reliable way, and to give teams robust debugging, testing, and verification functionality. For more information on the functionality available in the Svix App Portal, visit the Svix webhook consumer documentation.

How to trigger GitHub Actions workflows with outgoing webhooks

One common use case for outgoing webhooks is triggering CI/CD workflows when a specific event occurs in Runway. For example, you can configure an outgoing webhook in Runway to trigger a GitHub Actions workflow as soon as a release in Runway has been completed.

See below for instructions and an example on how to configure an outgoing webhook endpoint to trigger a GitHub Actions workflow when a specific event occurs.

Prerequisites

To configure an outgoing webhook to trigger a GitHub Actions workflow, you'll need:

1. A GitHub authentication token with the appropriate scopes. This can be either a personal access token or a GitHub App access token. For more details on the required scopes and permissions, visit GitHub's documentation.

2. A workflow that's configured to be run on workflow_dispatch events. For more details, see GitHub's documentation.

Setting up the webhook endpoint

1. Navigate to Organization settings > Webhooks > Add endpoint.

2. Enter the GitHub actions workflow dispatch endpoint in the Endpoint field. For example https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches replacing the path parameters with your respository's values.

3. (optional) Add a webhook endpoint description.

4. Choose the event types that should trigger your workflow. For example, to trigger your workflow when a release is completed, select the release.released event type.

5. Add your authentication token as a custom header to your endpoint. The header's key should be Authorization. The header's value should be Bearer {authToken} where {authToken} is your GitHub authentication token.

6. Click "Add" to save your new webhook endpoint.

Modifying the endpoint's payload

In order to properly trigger a workflow dispatch event to trigger your GitHub Actions workflow, you'll need to modify the webhook event's payload to include additional properties that are required to trigger a workflow run. To accomplish this, you can use endpoint transformations, which are configured from the Svix App Portal.

After you've added your new webhook endpoint, follow these steps to configure an endpoint payload transformation:

1. Go to the Svix App Portal to create a payload transformation for the new endpoint. Navigate to Organization settings > Webhooks > Go to App Portal.

2. In the list of Endpoints, find your workflow dispatch endpoint and click into its settings.

3. Navigate to the Advanced tab in the endpoint settings page.

4. In the Transformations section click Edit transformation.

5. Modify the webhook's payload and enable the transformation. For a workflow dispatch request payload, pass in the ref that the workflow should be triggered on, along with any inputs your workflow might require. Note that the ref field's value can be a branch or tag name, and you can pass through any part of the original webhook's payload.

For example, for an event type of release.released , you can access the release's branch as follows:

6. Click "Save" to save your endpoint transformation.