Webhooks¶

Webhooks notify external services, e.g. a CI server or a documentation builder, about events. An organization webhook receives the events of all repositories, a repository webhook only those of its repository.

Configure a secure webhook¶

orgs.newOrg('my-project', 'my-org') {
  webhooks+: [
    orgs.newOrgWebhook('https://ci.example.org/github-webhook/') {
      content_type: "json",
      events+: [
        "pull_request",
        "push",
      ],
      secret: "pass:path/to/ci-webhook-secret", // (1)!
    },
  ],
  _repositories+:: [
    orgs.newRepo('my-repo') {
      webhooks+: [
        orgs.newRepoWebhook('https://docs.example.org/hooks/my-repo') {
          content_type: "json",
          events+: [
            "push",
          ],
          secret: "pass:path/to/docs-webhook-secret",
        },
      ],
    },
  ],
}

1. A reference to a credential provider, see Secrets and variables.

Open in the Playground

Change the URL of a webhook¶

The URL identifies a webhook: changing it in the configuration deletes the webhook and creates a new one. To update the existing webhook instead, list the previous URL in aliases, see Renaming of Resources:

orgs.newOrg('my-project', 'my-org') {
  webhooks+: [
    orgs.newOrgWebhook('https://ci.example.org/hooks/github') {
      aliases: [
        "https://ci.example.org/github-webhook/", // (1)!
      ],
      content_type: "json",
      events+: [
        "pull_request",
        "push",
      ],
      secret: "pass:path/to/ci-webhook-secret",
    },
  ],
}

1. The previous URL: the existing webhook keeps its deliveries and settings, and only its URL is updated. The alias can be removed once the change has been applied.

Open in the Playground

Pause a webhook¶

To stop the deliveries temporarily, e.g. while the receiving service is migrated, set active: false instead of removing the webhook: its URL, events and secret are kept, and deliveries resume once it is active again.

Secrets after an import¶

After an import, the secret of a webhook is ******** and the webhook is skipped until the value is replaced by a reference to a credential provider. A rotated secret must be sent again explicitly. Both are described in SecretValue.

Remove webhooks that are not used anymore¶

Webhooks often outlive the service they were created for. A webhook pointing to a service that no longer exists fails on every delivery and sends the events of your repositories to a domain that you might not control anymore. Check the recent deliveries of webhooks in the GitHub web interface and remove the webhooks that are not used anymore from the configuration.