# Fireberry Webhooks

Fireberry (CRM, formerly Powerlink) sends webhooks from an **automation**: under **Then** you add a
**Webhook** action and choose the request method, URL, headers and body. Requests are **not
signed**. You authenticate them with a secret header that you add to the action yourself, and your
endpoint compares that header with the value you stored.

A static shared credential authenticates the **sender, not the body**, and gives **no replay
protection** (no signature, no timestamp). Use HTTPS, and rotate the credential if it leaks.

## When to Use This Skill

* How do I receive Fireberry webhooks?
* Does Fireberry sign webhook payloads? (No: use a secret header on the automation action)
* How do I authenticate a Fireberry webhook automation request?
* Why does my Fireberry webhook endpoint return 401?
* Why did my Fireberry automation switch to Draft?

## Verification (core)

In the webhook action, add a header (**+ Add Header**), e.g. key `Authorization`, value
`Bearer <long random secret>`. The header name is yours to choose, so read it from config, and
compare the **whole value** (do not strip or parse `Bearer `):

```javascript
const crypto = require('crypto');

function safeEqual(a, b) {
  const ba = Buffer.from(String(a), 'utf8');
  const bb = Buffer.from(String(b), 'utf8');
  return ba.length === bb.length && crypto.timingSafeEqual(ba, bb); // throws on unequal lengths
}

function verifyFireberryRequest(
  headers,
  secret = process.env.FIREBERRY_WEBHOOK_SECRET,          // exact whole header value
  headerName = process.env.FIREBERRY_WEBHOOK_HEADER || 'Authorization'
) {
  if (!secret) return false;                              // never accept when unconfigured
  const received = headers[headerName.toLowerCase()];     // Node lowercases header names
  return Boolean(received) && safeEqual(received, secret);
}

```

* Missing header or mismatch: `401`. Python: `hmac.compare_digest` on bytes (encode both sides;
  `str` raises on non-ASCII).
* Read the body raw (`express.raw({ type: '*/*' })`) so any content type works, and parse JSON only
  after the credential check.
* **The method is yours to choose.** The action offers POST, GET, PUT, DELETE and PATCH, so accept
  all five on the route and handle an empty body (the action has no body for GET).
* **Hookdeck:** Hookdeck's Fireberry source pre-selects POST only. If your automation uses
  another method, allow that method on the source.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/fireberry-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/fireberry-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/fireberry-webhooks/examples/fastapi/).

## Payload and Events

Fireberry adds **no event field** and defines no event types. The body is free text the automation's
author writes, with [field references](https://www.fireberry.com/articles/webhook-automations)
inserted from the record. The examples therefore use a clearly labelled **illustrative** JSON body
that you shape yourself in the action's Body box:

| `event` (illustrative) | Meaning in your automation |
| --- | --- |
| `account.created` | Automation "Account is created" |
| `record.updated` | Automation fires when a record changes |

```json
{"event": "account.created", "record": {"id": "a1b2c3", "accountname": "Acme Ltd"}}

```

## Environment Variables

```bash
FIREBERRY_WEBHOOK_HEADER=Authorization                    # header name you added (default Authorization)
FIREBERRY_WEBHOOK_SECRET="Bearer your-long-random-secret"  # exact whole value, incl. any "Bearer "

```

## Failed Webhooks

Fireberry does not retry a request. But if the action gets **5 consecutive error responses over more
than 24 hours, or 1,000 consecutive within 24 hours**, the whole automation is set to **Draft** and stops
running, and an email goes to the creator and the primary system user. Return 2xx for requests you
choose to ignore, and fix 401s (a wrong secret) promptly.

## Local Development

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

```bash
npx hookdeck-cli listen 3000 fireberry --path /webhooks/fireberry

```

Use the printed URL as the action's URL.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/fireberry-webhooks/references/overview.md) - How webhook automations work, payload shape
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/fireberry-webhooks/references/setup.md) - Add the Webhook action and the secret header
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/fireberry-webhooks/references/verification.md) - Header check details, gotchas, debugging 401s
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/fireberry-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests