n8n 'Deploy notify' workflow and heartbeat #4

Open
opened 2026-11-10 22:23:06 +01:00 by robin.wieske · 1 comment
Owner

Context

The notify action posts deploy events to one generic n8n workflow that forwards them to Signal. The same workflow watches heartbeats so a silently broken schedule is noticed.

Plan: https://forgejo.entwirr.me/Wi3eDigital/laravel-deploy-actions/src/branch/main/docs/plan.md (section "Notifications").

Tasks

  • n8n workflow "Deploy notify": webhook trigger, POST, header auth on X-Notify-Token (the credential is created by the owner, not in this issue)
  • Validate the payload (schema: 1, required fields per the plan)
  • Dedup: drop events with a dedup_key already seen in the last 24h, stored in an n8n data table
  • Routing: info events are logged only, except deploy.succeeded for env: prod; warn and critical are sent
  • Send to the same Signal user the other n8n workflows use
  • Record heartbeat events per repo (last seen) in a data table
  • Scheduled check: alert on Signal when a repo in scope has sent no heartbeat for more than 2 days
  • Weekly summary on Signal of repos in scope that never reported
  • Keep the list of repos in scope in one place (data table or workflow setting) and document it in the workflow description

Acceptance criteria

  • Requests without a valid X-Notify-Token are rejected
  • Payload fields match the plan schema; unknown events or a wrong schema are rejected or logged, not sent
  • The same dedup_key within 24h is sent once
  • info events are not sent, except prod deploy.succeeded
  • Missing heartbeat for more than 2 days raises one alert per repo (not every check run)
  • Weekly summary lists repos in scope that never sent anything
  • Test calls for each severity, a duplicate, and a bad token are run and the results noted in this issue

Blocked by

Nothing (the payload schema is fixed in the plan). Owner: create the n8n header auth credential.

## Context The `notify` action posts deploy events to one generic n8n workflow that forwards them to Signal. The same workflow watches heartbeats so a silently broken schedule is noticed. Plan: https://forgejo.entwirr.me/Wi3eDigital/laravel-deploy-actions/src/branch/main/docs/plan.md (section "Notifications"). ## Tasks - [ ] n8n workflow "Deploy notify": webhook trigger, `POST`, header auth on `X-Notify-Token` (the credential is created by the owner, not in this issue) - [ ] Validate the payload (`schema: 1`, required fields per the plan) - [ ] Dedup: drop events with a `dedup_key` already seen in the last 24h, stored in an n8n data table - [ ] Routing: `info` events are logged only, except `deploy.succeeded` for `env: prod`; `warn` and `critical` are sent - [ ] Send to the same Signal user the other n8n workflows use - [ ] Record `heartbeat` events per repo (last seen) in a data table - [ ] Scheduled check: alert on Signal when a repo in scope has sent no `heartbeat` for more than 2 days - [ ] Weekly summary on Signal of repos in scope that never reported - [ ] Keep the list of repos in scope in one place (data table or workflow setting) and document it in the workflow description ## Acceptance criteria - [ ] Requests without a valid `X-Notify-Token` are rejected - [ ] Payload fields match the plan schema; unknown events or a wrong `schema` are rejected or logged, not sent - [ ] The same `dedup_key` within 24h is sent once - [ ] `info` events are not sent, except prod `deploy.succeeded` - [ ] Missing heartbeat for more than 2 days raises one alert per repo (not every check run) - [ ] Weekly summary lists repos in scope that never sent anything - [ ] Test calls for each severity, a duplicate, and a bad token are run and the results noted in this issue ## Blocked by Nothing (the payload schema is fixed in the plan). Owner: create the n8n header auth credential.
Author
Owner

n8n workflows built (unpublished)

Both live in the personal project root (next to "PHP security patch watcher"). Neither is published yet.

Workflow ID Trigger
Deploy notify d9Tw3FIqnGOjfvG0 Webhook POST /webhook/deploy-notify (production URL https://n8n.entwirr.me/webhook/deploy-notify), header auth
Deploy notify: heartbeat check DQvPEV7oHPAgpdmv Daily 08:10 Europe/Berlin

Payload contract: docs/plan.md, "Notifications"

Data tables (same project):

  • deploy_notify_seen (kSYCGXG8hD16I6BJ): dedup_key, event, project, last_seen_at
  • deploy_notify_heartbeat (7zXqeREjuJRMalDr): project, repo, last_heartbeat_at, last_event, plus stale_alerted_at. I added that column so a stale repo gets one alert, not one per check run.

How Deploy notify works

  1. The webhook (header auth) feeds Validate payload. A payload is valid when:
    • schema === 1
    • event, severity, project and title are non-empty strings
    • event and severity are values from the plan's lists
    • reasons is an array, if present
  2. An invalid payload gets 400 {accepted:false, errors:[...]} and nothing is sent. A valid one gets 202 {accepted:true} straight away, then processing continues.
  3. A heartbeat event is upserted into deploy_notify_heartbeat, keyed on project. last_heartbeat_at is the n8n receive time, not the client ts. Heartbeats are never sent.
  4. Any other event looks up its dedup_key in deploy_notify_seen. If the key was seen within 24h, the event is dropped.
  5. Routing:
    • warn and critical are always sent.
    • info is only sent for deploy.succeeded with env: prod. Every other info event is logged in the execution and not sent.
  6. Messages go to Signal the same way as the other workflows: an HTTP POST to the signal-cli-rest-api /v2/send, with the same sender and recipient set in the Config node, and no credential. The dedup_key row is upserted after the send. The message format is:
    [CRITICAL] <project> <env> <version>: <title>
    <body>
    - <reason>
    <url>
    
  7. If the workflow fails, the "On failure" path sends a Signal alert, like the other workflows.

Heartbeat check

  • Repos in scope: aevana, slight-exposure, kima-portal, kima, kardeema, homepage. The list lives in the Config node (projects) and is also written in the workflow description.
  • Stale alert: a project in scope is alerted once when its last_heartbeat_at is more than 2 days old. It is alerted again only after a newer heartbeat arrives and then goes stale again. Projects that have never sent a heartbeat are not alerted daily, so repos that haven't been rolled out yet stay quiet.
  • Mondays: one summary message lists the projects in scope that never reported. Nothing is sent if that list is empty.

Test results

All tests were manual MCP test runs. Both Signal send nodes were pinned in every run, so no real Signal message was sent. The data table nodes ran against the real tables.

Case Execution Result
critical deploy.failed prod 13996 202, sent (pinned), seen row written. Message: [CRITICAL] test-notify prod v0.0.1: Deploy failed + body + 2 reason bullets + url
duplicate of the above (same dedup_key) 13998 dropped: "duplicate dedup_key within 24h"
info deploy.succeeded staging 13999 not sent: "info event, logged only"
info deploy.succeeded prod 14000 sent (pinned)
warn promote.due 14001 sent (pinned), reason bullet included
heartbeat 14002 upserted into deploy_notify_heartbeat, no lookup and no send
invalid (schema: 2, unknown event, no title) 14003 400 with 3 errors, 202 never reached, nothing sent
heartbeat check, Monday, fabricated rows 14004 aevana (3 days stale, not yet alerted) alerted. kima (stale, already alerted) suppressed. slight-exposure (fresh) not alerted. Summary listed kima-portal, kardeema, homepage.
heartbeat check, mark alerted 14005 stale_alerted_at written on the matching row
heartbeat check, Tuesday, real table 14006 nothing sent: no Monday summary, and the out-of-scope test-notify row was ignored
bad / missing X-Notify-Token n/a pending: can only be tested once the credential is attached (see below)

Test rows left in the tables (out-of-scope project test-notify, so they never alert):

  • deploy_notify_seen: test:deploy.failed:v0.0.1, test:deploy.succeeded:prod:v0.0.2, test:promote.due:v0.0.3
  • deploy_notify_heartbeat: test-notify

They can be deleted in the n8n UI.

Owner TODO

  1. In n8n, create a Header Auth credential with name X-Notify-Token and a random value as the token.
  2. Open Deploy notify and attach that credential to the Deploy notify webhook node. Header authentication is already selected there; only the credential is missing.
  3. Publish Deploy notify and Deploy notify: heartbeat check.
  4. Run the bad-token test against the production URL. Expected results:
    • no header or a wrong token → rejected (401/403), no execution
    • the right token and a valid body → 202
  5. Set the repo/org secrets:
    • DEPLOY_NOTIFY_URL = https://n8n.entwirr.me/webhook/deploy-notify
    • DEPLOY_NOTIFY_TOKEN = the token value
## n8n workflows built (unpublished) Both live in the personal project root (next to "PHP security patch watcher"). Neither is published yet. | Workflow | ID | Trigger | |---|---|---| | **Deploy notify** | `d9Tw3FIqnGOjfvG0` | Webhook `POST /webhook/deploy-notify` (production URL `https://n8n.entwirr.me/webhook/deploy-notify`), header auth | | **Deploy notify: heartbeat check** | `DQvPEV7oHPAgpdmv` | Daily 08:10 Europe/Berlin | Payload contract: [docs/plan.md, "Notifications"](https://forgejo.entwirr.me/Wi3eDigital/laravel-deploy-actions/src/branch/main/docs/plan.md#notifications) Data tables (same project): - `deploy_notify_seen` (`kSYCGXG8hD16I6BJ`): dedup_key, event, project, last_seen_at - `deploy_notify_heartbeat` (`7zXqeREjuJRMalDr`): project, repo, last_heartbeat_at, last_event, plus **`stale_alerted_at`**. I added that column so a stale repo gets one alert, not one per check run. ### How Deploy notify works 1. The webhook (header auth) feeds **Validate payload**. A payload is valid when: - `schema === 1` - `event`, `severity`, `project` and `title` are non-empty strings - `event` and `severity` are values from the plan's lists - `reasons` is an array, if present 2. An invalid payload gets **400** `{accepted:false, errors:[...]}` and nothing is sent. A valid one gets **202** `{accepted:true}` straight away, then processing continues. 3. A `heartbeat` event is upserted into `deploy_notify_heartbeat`, keyed on `project`. `last_heartbeat_at` is the n8n receive time, not the client `ts`. Heartbeats are never sent. 4. Any other event looks up its `dedup_key` in `deploy_notify_seen`. If the key was seen within 24h, the event is dropped. 5. Routing: - `warn` and `critical` are always sent. - `info` is only sent for `deploy.succeeded` with `env: prod`. Every other `info` event is logged in the execution and not sent. 6. Messages go to Signal the same way as the other workflows: an HTTP POST to the signal-cli-rest-api `/v2/send`, with the same sender and recipient set in the `Config` node, and no credential. The `dedup_key` row is upserted **after** the send. The message format is: ``` [CRITICAL] <project> <env> <version>: <title> <body> - <reason> <url> ``` 7. If the workflow fails, the "On failure" path sends a Signal alert, like the other workflows. ### Heartbeat check - **Repos in scope:** `aevana, slight-exposure, kima-portal, kima, kardeema, homepage`. The list lives in the `Config` node (`projects`) and is also written in the workflow description. - **Stale alert:** a project in scope is alerted once when its `last_heartbeat_at` is more than 2 days old. It is alerted again only after a newer heartbeat arrives and then goes stale again. Projects that have never sent a heartbeat are not alerted daily, so repos that haven't been rolled out yet stay quiet. - **Mondays:** one summary message lists the projects in scope that never reported. Nothing is sent if that list is empty. ## Test results All tests were manual MCP test runs. Both Signal send nodes were pinned in every run, so **no real Signal message was sent**. The data table nodes ran against the real tables. | Case | Execution | Result | |---|---|---| | critical `deploy.failed` prod | 13996 | 202, sent (pinned), seen row written. Message: `[CRITICAL] test-notify prod v0.0.1: Deploy failed` + body + 2 reason bullets + url | | duplicate of the above (same `dedup_key`) | 13998 | dropped: "duplicate dedup_key within 24h" | | info `deploy.succeeded` staging | 13999 | not sent: "info event, logged only" | | info `deploy.succeeded` prod | 14000 | sent (pinned) | | warn `promote.due` | 14001 | sent (pinned), reason bullet included | | heartbeat | 14002 | upserted into `deploy_notify_heartbeat`, no lookup and no send | | invalid (`schema: 2`, unknown event, no title) | 14003 | **400** with 3 errors, 202 never reached, nothing sent | | heartbeat check, Monday, fabricated rows | 14004 | aevana (3 days stale, not yet alerted) alerted. kima (stale, already alerted) suppressed. slight-exposure (fresh) not alerted. Summary listed kima-portal, kardeema, homepage. | | heartbeat check, mark alerted | 14005 | `stale_alerted_at` written on the matching row | | heartbeat check, Tuesday, real table | 14006 | nothing sent: no Monday summary, and the out-of-scope `test-notify` row was ignored | | **bad / missing `X-Notify-Token`** | n/a | **pending**: can only be tested once the credential is attached (see below) | Test rows left in the tables (out-of-scope project `test-notify`, so they never alert): - `deploy_notify_seen`: `test:deploy.failed:v0.0.1`, `test:deploy.succeeded:prod:v0.0.2`, `test:promote.due:v0.0.3` - `deploy_notify_heartbeat`: `test-notify` They can be deleted in the n8n UI. ## Owner TODO 1. In n8n, create a **Header Auth** credential with name `X-Notify-Token` and a random value as the token. 2. Open **Deploy notify** and attach that credential to the **Deploy notify webhook** node. Header authentication is already selected there; only the credential is missing. 3. Publish **Deploy notify** and **Deploy notify: heartbeat check**. 4. Run the bad-token test against the production URL. Expected results: - no header or a wrong token → rejected (401/403), no execution - the right token and a valid body → 202 5. Set the repo/org secrets: - `DEPLOY_NOTIFY_URL` = `https://n8n.entwirr.me/webhook/deploy-notify` - `DEPLOY_NOTIFY_TOKEN` = the token value
Sign in to join this conversation.
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
You do not have permission to read 1 dependency
Reference
Wi3eDigital/laravel-deploy-actions#4
No description provided.