# Jenkins

EvoHub receives Jenkins builds in one JSON shape, sent either by the **Notification** plugin or by a `curl` step in a pipeline. A failed build pages; the next successful build of the same job and branch resolves it.

## Option A: Notification plugin

:::steps
### Create the integration
In EvoHub, go to **On-Call → Integrations → + Add Integration**, choose **Jenkins**, pick an **Escalation Policy** and click **Create Integration**. Copy the **Webhook URL**.
### Install the plugin
In Jenkins, go to **Manage Jenkins → Plugins** and install **Notification**.
### Add the endpoint
Open the job's **Configure → Job Notifications → Add Endpoint**. Set **Format** to JSON, **Protocol** to HTTP, **Event** to *Job Completed*, and **URL** to your webhook URL.
:::

The plugin cannot send headers. To use a signing secret with it, generate one in EvoHub and put it into the URL as a password: `https://evohub:<signing secret>@` followed by the rest of the URL. A generated secret contains only letters and digits, so it needs no escaping.

## Option B: curl from a Jenkinsfile

Store the webhook URL and the signing secret as Jenkins credentials exposed as `EVOHUB_URL` and `EVOHUB_SECRET`, then add:

```groovy
post {
  failure { sh '''curl -fsS -X POST "$EVOHUB_URL" -H 'Content-Type: application/json' -H "X-EvoHub-Token: $EVOHUB_SECRET" -d "{\\"name\\":\\"$JOB_NAME\\",\\"build\\":{\\"number\\":$BUILD_NUMBER,\\"status\\":\\"FAILURE\\",\\"full_url\\":\\"$BUILD_URL\\",\\"scm\\":{\\"branch\\":\\"$BRANCH_NAME\\"}}}"''' }
  fixed   { sh '''curl -fsS -X POST "$EVOHUB_URL" -H 'Content-Type: application/json' -H "X-EvoHub-Token: $EVOHUB_SECRET" -d "{\\"name\\":\\"$JOB_NAME\\",\\"build\\":{\\"number\\":$BUILD_NUMBER,\\"status\\":\\"SUCCESS\\",\\"full_url\\":\\"$BUILD_URL\\",\\"scm\\":{\\"branch\\":\\"$BRANCH_NAME\\"}}}"''' }
}
```

`fixed` runs on the first green build after a failure, which is what resolves the alert.

## What pages

| Build result | EvoHub |
| --- | --- |
| `FAILURE` | opens a **high** alert |
| `UNSTABLE` | opens a **medium** alert |
| `SUCCESS` | resolves the alert of the same job and branch |
| `ABORTED`, `NOT_BUILT` | nothing |

Only the **COMPLETED** phase counts. The plugin's QUEUED, STARTED and FINALIZED notifications are answered `200` and do nothing; a body with a result and no phase, like the curl step's, counts as completed.

## What EvoHub reads

| EvoHub alert | Taken from |
| --- | --- |
| Title | Job, build number, result and branch — for example *shop #42 FAILURE on origin/main*. |
| Labels | `job`, `branch`, `status`, `commit`, and `url` — the build's `full_url`. |

## Resolve and deduplication

An alert is identified by the job name and the branch (`build.scm.branch`). While it is open, another failure is recorded as **Retriggered** instead of paging again.

## Signature

With a signing secret set, every delivery must carry it — as the Basic-auth password in the URL or in the `X-EvoHub-Token` header. Anything else is refused with `403` and opens nothing. See [Signing secrets](https://docs-dev.evohub.io/integrations-overview.md#signing-secrets).

## Related

- [Integrations overview](https://docs-dev.evohub.io/integrations-overview.md)
- [GitHub](https://docs-dev.evohub.io/github.md)
- [GitLab](https://docs-dev.evohub.io/gitlab.md)