Agent skill

Honeybadger Webhooks Skill

Receive and authenticate Honeybadger webhooks. Use when setting up a Honeybadger webhook endpoint, verifying the Honeybadger-Token header, debugging 401s, or handling error and uptime events like occurred, resolved, down, up, check_in_missing and deployed.

Install this skill

npx skills add hookdeck/webhook-skills --skill honeybadger-webhooks

Honeybadger sends a JSON webhook when something happens in a project: an error occurs or is resolved, an uptime check goes down, a check-in is missed, a deploy is recorded. Webhooks are not signed. Every request carries a Honeybadger-Token header, a secret token derived from your project API key, and your endpoint authenticates the request by comparing that header with the token you have stored.

When to Use This Skill

How do I receive Honeybadger webhooks?
How do I verify the Honeybadger-Token header?
Does Honeybadger sign webhook payloads? (No: use the shared token)
How do I handle occurred, resolved, down or check_in_missing events?
Why does my Honeybadger webhook endpoint return 401 after I reset the API key?

Verification (core)

const crypto = require('crypto');

// Hash both sides: equal-length buffers, so timingSafeEqual never throws.
function safeEqual(a, b) {
  const ha = crypto.createHash('sha256').update(String(a)).digest();
  const hb = crypto.createHash('sha256').update(String(b)).digest();
  return crypto.timingSafeEqual(ha, hb);
}

function verifyHoneybadgerRequest(headers, token = process.env.HONEYBADGER_TOKEN) {
  if (!token) return false;                       // never accept when unconfigured
  const received = headers['honeybadger-token'];  // raw token, no prefix
  return Boolean(received) && safeEqual(received, token);
}

Header: Honeybadger-Token: <token> (sent raw, no Bearer prefix). Find the token on the API Key tab of the project settings.
Do not use the optional Authorization: Bearer field from the webhook integration settings. It exists only for services that reject requests without an Authorization header; check Honeybadger-Token.
Return 401 on mismatch, 400 for a body that isn't a JSON object, 200 once handled.
Read the body raw (express.raw({ type: '*/*' })) and authenticate before parsing it.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Types

The payload has an event field and a human-readable message; the rest depends on the event.

Event	Sent When
`occurred`	An error occurs
`resolved`	An error is marked as resolved
`unresolved`	A resolved error occurs again
`assigned`	An error is assigned to a user
`commented`	A comment is added to an error
`rate_exceeded`	The error rate threshold is exceeded
`volume_spike`	Error volume spikes above its learned baseline
`deployed`	A deployment is recorded
`down`	An uptime check fails
`up`	An uptime check succeeds after being down
`cert_will_expire`	An SSL certificate is about to expire
`check_in_missing`	An expected check-in is missing
`check_in_reporting`	A check-in reports successfully

Environment Variables

HONEYBADGER_TOKEN=your-project-token   # Project Settings > API Key tab

The token changes if you reset the project API key; update the variable when you do.

Local Development

Honeybadger can't reach localhost. Tunnel with the Hookdeck CLI (no account required):

npx hookdeck-cli listen 3000 honeybadger --path /webhooks/honeybadger

Use the printed URL as the webhook URL in Honeybadger.

Resources

references/overview.md - What Honeybadger webhooks are, events and payload shape
references/setup.md - Add the Webhook integration and find the token
references/verification.md - Token check details, gotchas, debugging 401s
examples/ - Runnable Express, Next.js and FastAPI handlers with tests