> For the complete documentation index, see [llms.txt](https://docs.spike.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spike.sh/integrations-guideline/integrate-spike-with-keysight-hawkeye.md).

# Integrate Spike with Keysight Hawkeye

Send Keysight Hawkeye alarm emails to Spike so a failed network test pages your on-call rotation, and the incident resolves when the test passes again.

[Keysight Hawkeye](https://www.keysight.com) is an active network monitoring platform. Hawkeye agents run tests between endpoints, such as VoIP quality, packet loss or web page load, and raise an alarm when a result crosses a threshold.

Hawkeye sends its alarms by email through the SMTP server configured in its preferences. Spike gives every email integration its own address, so you point Hawkeye's alarm emails at that address and a failed test becomes an incident. There is no inbox: Spike reads the mail and discards it.

{% hint style="warning" %}
We could not find a real Hawkeye alarm email to build this against. The subject and body wording below follows Hawkeye's documented behaviour (a predefined title and test-results layout that cannot be customised) but is illustrative. If your alarms look different, send us one at <support@spike.sh>.
{% endhint %}

## Step 1: Create the integration in Spike

1. From the header, click [Add integration](https://app.spike.sh/integrations/new).
2. Select **Keysight Hawkeye** and give the integration a name.
3. Click create, then copy the email address shown on the integration page. It looks like `9f3c2a7b51d04e8a6c1f@email-hooks.spike.sh`.

## Step 2: Point Hawkeye's alarm emails at Spike

1. In Hawkeye, go to **Administration** > **Preferences** > **Email (SMTP)** and fill in the SMTP settings so Hawkeye can send mail. The sender address you set here is stored on the incident for display.
2. Open the test you want to be paged for and click **Show Alarm Options**.
3. Under **Set Alarm On**, add the Spike email address as the alarm email recipient. It is the only setting Spike needs.
4. Choose what the alarm fires on: **Failed**, **Error** and **Status Change**. Tick **Status Change** (alarm when a result differs from the previous run) if you want Spike to resolve the incident when the test passes again.
5. Save the test.

## What Hawkeye sends, and what Spike reads

Spike reads these parts of the email:

| Field      | Required | What Spike does with it                                                                                                                                                    |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`       | Yes      | Carries the integration token in the `<token>@email-hooks.spike.sh` address.                                                                                               |
| `subject`  | Yes      | Hawkeye's predefined alarm title, one per test. It identifies the alarm, so a repeat joins the open incident and the recovery resolves it.                                 |
| `text`     | Yes      | The test-results body. Its first line that is not a `Key: value` pair becomes the incident title, and its `Status:` line decides whether the alarm is firing or recovered. |
| `html`     | No       | Used only when `text` is empty; Spike converts it to text.                                                                                                                 |
| `envelope` | No       | Its recipients are also checked for the token when the mail was forwarded.                                                                                                 |
| `from`     | No       | The sender address, shown in the incident details.                                                                                                                         |

A firing alarm looks like this:

```json
{
  "to": "9f3c2a7b51d04e8a6c1f@email-hooks.spike.sh",
  "from": "Hawkeye <hawkeye-alarms@netops.example.com>",
  "subject": "Hawkeye Alarm: Branch-NYC to DC1 VoIP MOS",
  "text": "Test Branch-NYC to DC1 VoIP MOS failed: MOS 3.1 is below the threshold of 4.0 between nyc-branch-01 and dc1-core-02.\n\nTest name: Branch-NYC to DC1 VoIP MOS\nStatus: Failed\nSource endpoint: nyc-branch-01\nDestination endpoint: dc1-core-02\nKPI: MOS 3.1 (threshold 4.0)\nRun time: 2026-10-08 03:12:44 UTC",
  "envelope": "{\"to\":[\"9f3c2a7b51d04e8a6c1f@email-hooks.spike.sh\"],\"from\":\"hawkeye-alarms@netops.example.com\"}"
}
```

The recovery for the same test:

```json
{
  "to": "9f3c2a7b51d04e8a6c1f@email-hooks.spike.sh",
  "from": "Hawkeye <hawkeye-alarms@netops.example.com>",
  "subject": "Hawkeye Alarm: Branch-NYC to DC1 VoIP MOS",
  "text": "Test Branch-NYC to DC1 VoIP MOS passed: MOS is back within threshold between nyc-branch-01 and dc1-core-02.\n\nTest name: Branch-NYC to DC1 VoIP MOS\nStatus: Passed\nSource endpoint: nyc-branch-01\nDestination endpoint: dc1-core-02\nKPI: MOS 4.3 (threshold 4.0)\nRun time: 2026-10-08 03:27:44 UTC",
  "envelope": "{\"to\":[\"9f3c2a7b51d04e8a6c1f@email-hooks.spike.sh\"],\"from\":\"hawkeye-alarms@netops.example.com\"}"
}
```

## Step 3: Test it

Use a test whose threshold you can trip on purpose, or send an email yourself: to your Spike address, with the subject `Hawkeye Alarm: Branch-NYC to DC1 VoIP MOS` and the firing example's `text` value as its plain-text body. An incident should appear. Then send a second email with the same subject and the recovery example's `text` value as its body, and the incident resolves. The examples above show how the email reaches Spike; they are not themselves something you can send.

## Incident identity

Spike identifies the incident by the email **subject**. Hawkeye uses one predefined subject per test, so every alarm for that test lands on the same incident, and the recovery email resolves it. If Hawkeye put the status in the subject, a recovery would not match and the incident would stay open until someone resolves it.

If a mail has no subject (or an unfilled placeholder such as `{subject}`), Spike cannot tell which test it is about. It titles the incident with the constant `Keysight Hawkeye alarm with no subject` and matches on that, so all such mails share one incident, which never resolves itself.

## Incident title

The title is Hawkeye's own sentence about the fault: the first line of the body that is not a `Key: value` pair, whitespace collapsed and capped at 200 characters. For the firing alarm above it is:

```
Test Branch-NYC to DC1 VoIP MOS failed: MOS 3.1 is below the threshold of 4.0 between nyc-branch-01 and dc1-core-02.
```

The readings can change between runs; that does not split the incident, because Spike matches on the subject. The recovery email is titled by its own sentence (`Test Branch-NYC to DC1 VoIP MOS passed: ...`), and the incident keeps the title it opened with. When the body has no such sentence the title is the subject (with `recovered` appended for a passed email), an email with no subject is titled `Keysight Hawkeye alarm with no subject`, and an email with neither is titled `Keysight Hawkeye alert with no details`.

## What resolves an incident

Spike reads the `Status:` line in the body:

| `Status` | Meaning                      | Result                                       |
| -------- | ---------------------------- | -------------------------------------------- |
| `Failed` | The test failed.             | Opens or updates an incident and pages.      |
| `Error`  | The test could not run.      | Opens or updates an incident and pages.      |
| `Passed` | The test is back to passing. | Resolves the incident with the same subject. |

`Passed` is read in any letter case, and the closed-like values `Resolved`, `Closed`, `OK` and `Cleared` count as a recovery too. A recovery never opens an incident: with nothing open for that subject it is dropped. Any other value, or a missing `Status:` line, opens or updates an incident. Resolving in Spike does not change anything in Hawkeye.

{% hint style="warning" %}
Auto-resolve depends on Hawkeye sending a recovery email, which happens with the **Status Change** alarm option, and on the subject being the same in the failure and the recovery email. Spike resolves on a `Status: Passed` email as described above, but this has not yet been confirmed against a real Hawkeye recovery email, so the Spike integrations page does not list Keysight Hawkeye as auto-resolving yet. Until you have seen one of your incidents resolve this way, also set a [resolve timer](https://docs.spike.sh/incidents/resolve-timer.md). There is a 30 MB payload limit.
{% endhint %}
