Cirrus-ci-docs: Add support for webhooks for build results

[yschimke]

Useful for building notifications based on build results

[cevich]

This is related to #50 but I'd suggest expanding the scope to also include: NeedsApproval hooks. For a large project with many contributors, it's hard to keep up with what's happening. In addition to knowing about success/failure, it would be nice to be know when someone needs to review and approve a cirrus-ci run.

[fkorotkov]

@cevich there will be 4 types of webhook events pretty soon:

1. Build creation.
2. Build status update (for example CREATED -> NEEDS_APPROVAL).
3. Task creation.
4. Task status update (for example EXECUTING -> FAILED).

🙌

[cevich]

Oh yay! Def :clap: :clap:

[fkorotkov]

Here is a finalized proposal of webhooks which is almost ready to hit the production:

There will be a per-organization setting to configure a URL where the webhook events will be POSTed. Each delivery will have:

1. X-Cirrus-Event header with value build or task for updates to builds or tasks respectively.
2. Payload will be a JSON object with two top-level fields: action and data
   
   
   
   • action will be either created or updated.
   
   
   • data will contain data about repository, build and task (if any) for the corresponding event.
   
   

data will be created by running the following GraphQL query:

repository(id: $repositoryId) {
  id
  owner
  name
  isPrivate
}
build(id: $buildId) {
  id
  name
  branch
  changeIdInRepo
  status
  changeTimestamp
}
task(id: $taskId) {
  id
  name
  status
  creationTimestamp
  finalStatusTimestamp
}

which will result in a payload like this:

{
  "action": "created",
  "data": {
    "repository": { ... },
    "build": { ... },
    "task": { ... },
  }
}

In future we can consider to add a feature to customize the query. Please take a look if something is missing for your usecase and let me know before this change is deployed in the next few days.

[dbolkensteyn]

How are delivery failures going to be handled: Will they be retried, i.e. should the receiving service be idempotent? Which criteria determines a successful delivery, e.g. HTTP 200 response?

In terms of security, will the deliveries be signed, or should the endpoint URL remain secret?

[fkorotkov]

There will be a single retry for 500's and 200 will be treated as a success.

Eventually it will mock how GitHub's webhooks are working and there will be X-Cirrus-Signature generated for the payload. At the moment it's not implemented but will be added right after the initial release.

[xavierbourguignon]

What are the different statuses we will receive ?

[fkorotkov]

@xavierbourguignon same as in GraphQL API for consistency. 🙌

Here are links to GraphQL Schema for tasks and for builds.

[cevich]

Might be useful to have the github username/author. Though I s'pose that could be gleaned by other means. Otherwise LGTM.

[fkorotkov]

Notification are available now to configure on your organization's settings page: https://cirrus-ci.com/settings/github/

Please give it a try. Will close the issue once documentation is added.

[fkorotkov]

Documented in 13828d0cf7ed30da69a042a8ae250d9bd4800d68