# Webhooks

> Receive alerts, new scripts and finished reports on your endpoint, verify the HMAC signature and handle retries.

URL: https://docs.proteside.com/en/docs/api/webhooks

With a webhook, Proteside sends a `POST` to your endpoint as soon as something happens: a new alert, an unknown script
on the checkout, a finished PCI DSS report. You don't need to keep polling the API.

Webhooks, Slack, Microsoft Teams and email are all **notification channels** of the same organization. What you
create through the API shows up in **Settings → Notifications**, and vice versa.

## Create a webhook
  **Dashboard**

      Open **Settings → Notifications** and click **Add channel**. You need to be an owner or admin.

      Choose the **Webhook** type and the scope: **This store** (only events from the selected store) or **Organization**
(events from every store). Type and scope can't be changed later.

      Fill in **Name** and **URL** (it must start with `https://`) and leave **Format** set to **JSON (signed)**.

      Fill in **Signing secret** with a random value of 16 to 128 characters and keep it safe: you'll need it to verify
deliveries.

      Choose the **Minimum severity** and the **Events**, keep **Channel active** on and click **Save changes**.

    

    > **No secret, no signature**
>
> In the dashboard, the secret is optional. If you leave the field empty, deliveries go out **without** the
> `X-Proteside-Signature` header and the channel card shows "unsigned". Always fill in the secret on JSON webhooks.

  **API**

Use `POST /webhooks` with a token that has the `webhooks:manage` scope:

    ```bash
    curl -s -X POST "https://app.proteside.com/api/v1/webhooks" \
      -H "Authorization: Bearer $PROTESIDE_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://ops.mystore.com/hooks/proteside",
        "name": "Production SIEM",
        "events": ["alert.created", "integrity.changed", "script.detected", "report.ready"],
        "min_severity": "medium"
      }'
    ```

    ```json
    {
      "id": "a9b8c7d6-5555-4666-8777-888899990000",
      "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
      "store_id": null,
      "type": "webhook",
      "name": "Production SIEM",
      "url": "https://ops.mystore.com/hooks/proteside",
      "format": "json",
      "has_secret": true,
      "events": ["alert.created", "integrity.changed", "script.detected", "report.ready"],
      "min_severity": "medium",
      "active": true,
      "last_used_at": null,
      "created_at": "2026-10-06T12:10:00.000Z",
      "updated_at": "2026-10-06T12:10:00.000Z",
      "secret": "whsec_YOUR_SECRET",
      "secret_generated": true
    }
    ```

    The `secret` field appears **only in this response**. If you don't send a `secret` (16 to 256 characters), the API
    generates one in the `whsec_…` format.

    - `url` (`string`): A public https:// address, with no username or password in the URL.
- `secret` (`string`): Signing secret, 16 to 256 characters. If omitted, one is generated automatically.
- `format` (`'json' | 'slack' | 'teams'`), default: `'json'`: Body format. Can't be changed later.
- `name` (`string`), default: `'Webhook · <host>'`: Name shown in the dashboard.
- `store_id` (`string (UUID)`): Restricts the channel to one store's events. If omitted: every store in the organization.
- `events` (`string[]`): Events the channel receives. null or []: all of them.
- `min_severity` (`'critical' | 'high' | 'medium' | 'low' | 'info'`), default: `'high'`: Minimum severity for alert events.
- `active` (`boolean`), default: `true`: Channel active.

    To change the URL, events, severity, name or state, or to rotate the secret, use
    [`PATCH /webhooks/{id}`](https://docs.proteside.com/en/docs/api/reference/webhooks/updateWebhook). To delete it, use
    [`DELETE /webhooks/{id}`](https://docs.proteside.com/en/docs/api/reference/webhooks/deleteWebhook): the channel's delivery history is deleted with it.

## Events
| Event               | When it's sent                                                                   | `severity`  | Filtered by `min_severity` |
| ------------------- | -------------------------------------------------------------------------------- | ----------- | -------------------------- |
| `alert.created`     | A new alert is opened, including CSP violations                                  | the alert's | yes                        |
| `alert.resolved`    | An SDK silent alert resolves itself because the SDK started sending events again | `medium`    | yes                        |
| `integrity.changed` | An authorized script's content changed (`SCRIPT_INTEGRITY_MISMATCH` alert)       | `high`      | yes                        |
| `header.changed`    | A security header on the payment page changed (`HEADER_CHANGED` alert)           | `medium`    | yes                        |
| `sdk.silent`        | A store with traffic stopped sending SDK events (`SDK_SILENT` alert)             | `medium`    | yes                        |
| `script.detected`   | A new script appeared on the checkout and is awaiting review                     | `info`      | no                         |
| `policy.applied`    | An approval policy decided on a script (automatic mode or **Apply**)             | `info`      | no                         |
| `report.ready`      | The scheduled PCI DSS report is ready                                            | `info`      | no                         |
| `test`              | You sent a test                                                                  | `info`      | ignores all filters        |

### Channel filters
Each channel has two filters:

* **`events`**: the list of accepted events. Empty or `null` means all of them.
* **`min_severity`**: applies only to alert events (`alert.created`, `alert.resolved`, `integrity.changed`,
  `header.changed` and `sdk.silent`). `script.detected`, `policy.applied` and `report.ready` always go through.

> **Choose the minimum severity**
>
> New channels use `min_severity: high` (**High and above**). To know when the SDK stopped running and also receive
> `header.changed` and medium-severity alerts, use `min_severity: "medium"` (**Medium and above**).

## Delivery format
Proteside makes a `POST` with a JSON body and these headers:

| Header                  | Content                                                                     |
| ----------------------- | --------------------------------------------------------------------------- |
| `Content-Type`          | `application/json`                                                          |
| `User-Agent`            | `Proteside-Webhooks/1.0`                                                    |
| `X-Proteside-Event`     | The event type, for example `alert.created`                                 |
| `X-Proteside-Delivery`  | The delivery ID (unique per channel and event, the same across all retries) |
| `X-Proteside-Signature` | `t=<unix>,v1=<hex>` (present when the channel has a secret)                 |

Every event uses the same envelope:

- `id` (`string`): Event ID (evt_ + 32 hex). The same across all channels and all retries.
- `type` (`string`): Event type.
- `created_at` (`string`): Event date (ISO-8601, UTC).
- `org_id` (`string`): The event's organization.
- `store_id` (`string | null`): The event's store, when there is one.
- `severity` (`string`): critical, high, medium, low or info.
- `data` (`object`): Event data. When there is a store, it includes data.store with id, name and domain.

### Payload examples
### alert.created

```json
{
  "id": "evt_5d41402abc4b2a76b9719d911017c592",
  "type": "alert.created",
  "created_at": "2026-10-06T09:40:01.123Z",
  "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "store_id": "0c1d2e3f-1111-4222-8333-444455556666",
  "severity": "critical",
  "data": {
    "alert": {
      "id": "e1f2a3b4-8888-4999-8000-111122223333",
      "type": "PIX_TAMPERED",
      "severity": "critical",
      "occurrences": 1,
      "page": "/checkout/payment",
      "details": { "reason": "untrusted_recipient", "method": "pix" },
      "first_seen_at": "2026-10-06T09:40:00.000Z",
      "source": "sdk",
      "url": "https://app.proteside.com/alerts/e1f2a3b4-8888-4999-8000-111122223333"
    },
    "store": {
      "id": "0c1d2e3f-1111-4222-8333-444455556666",
      "name": "My Store",
      "domain": "mystore.com"
    }
  }
}
```

`alert.resolved`, `integrity.changed`, `header.changed` and `sdk.silent` use the same `data.alert` format.

### integrity.changed

```json
{
  "id": "evt_7c9e6679f4e14b2a8f0e2d3c4b5a6978",
  "type": "integrity.changed",
  "created_at": "2026-10-06T10:15:02.000Z",
  "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "store_id": "0c1d2e3f-1111-4222-8333-444455556666",
  "severity": "high",
  "data": {
    "alert": {
      "id": "c3d4e5f6-2222-4333-8444-555566667777",
      "type": "SCRIPT_INTEGRITY_MISMATCH",
      "severity": "high",
      "occurrences": 1,
      "page": "/",
      "details": {
        "scriptId": "b2c3d4e5-6666-4777-8888-999900001111",
        "src": "https://cdn.fornecedor.example/widget.js",
        "authorizedHashPrefix": "9b74c9897bac770f",
        "currentHashPrefix": "1f3870be274f6c49",
        "hashSource": "verifier",
        "previousStatus": "authorized"
      },
      "first_seen_at": "2026-10-06T10:15:00.000Z",
      "source": "system",
      "url": "https://app.proteside.com/alerts/c3d4e5f6-2222-4333-8444-555566667777"
    },
    "store": { "id": "0c1d2e3f-1111-4222-8333-444455556666", "name": "My Store", "domain": "mystore.com" }
  }
}
```

### sdk.silent

```json
{
  "id": "evt_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "type": "sdk.silent",
  "created_at": "2026-10-06T11:00:04.000Z",
  "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "store_id": "0c1d2e3f-1111-4222-8333-444455556666",
  "severity": "medium",
  "data": {
    "alert": {
      "id": "d4e5f6a7-3333-4444-8555-666677778888",
      "type": "SDK_SILENT",
      "severity": "medium",
      "occurrences": 1,
      "page": "/",
      "details": {
        "lastEventAt": "2026-10-05T10:58:00.000Z",
        "silentHours": 24,
        "domain": "mystore.com",
        "host": "mystore.com",
        "page": "/"
      },
      "first_seen_at": "2026-10-06T11:00:00.000Z",
      "source": "system",
      "url": "https://app.proteside.com/alerts/d4e5f6a7-3333-4444-8555-666677778888"
    },
    "store": { "id": "0c1d2e3f-1111-4222-8333-444455556666", "name": "My Store", "domain": "mystore.com" }
  }
}
```

### script.detected

```json
{
  "id": "evt_9f86d081884c7d659a2feaa0c55ad015",
  "type": "script.detected",
  "created_at": "2026-10-06T09:12:30.000Z",
  "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "store_id": "0c1d2e3f-1111-4222-8333-444455556666",
  "severity": "info",
  "data": {
    "script": {
      "id": "f6a7b8c9-4444-4555-8666-777788889999",
      "src": "https://cdn.novo-fornecedor.example/tag.js",
      "type": "unknown",
      "category": null,
      "status": "needs_review",
      "vendor_id": null,
      "size_bytes": 18234,
      "gtm_container": null,
      "first_seen_at": "2026-10-06T09:12:29.000Z"
    },
    "store": { "id": "0c1d2e3f-1111-4222-8333-444455556666", "name": "My Store", "domain": "mystore.com" }
  }
}
```

### policy.applied

```json
{
  "id": "evt_2c26b46b68ffc68ff99b453c1d304134",
  "type": "policy.applied",
  "created_at": "2026-10-06T09:13:00.000Z",
  "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "store_id": "0c1d2e3f-1111-4222-8333-444455556666",
  "severity": "info",
  "data": {
    "script": {
      "id": "b2c3d4e5-6666-4777-8888-999900001111",
      "src": "https://www.googletagmanager.com/gtm.js",
      "status": "authorized",
      "type": "known_third",
      "category": "tag_manager"
    },
    "policy": { "id": "a1b2c3d4-5555-4666-8777-888899990000", "name": "Catalog analytics", "version": 1 },
    "action": "authorize",
    "justification": "Marketing tag manager, no access to payment fields.",
    "expires_at": "2027-01-04T09:13:00.000Z",
    "actor": "api:ps_live_YOUR_PREFIX",
    "store": { "id": "0c1d2e3f-1111-4222-8333-444455556666", "name": "My Store", "domain": "mystore.com" }
  }
}
```

### report.ready

```json
{
  "id": "evt_fcde2b2edba56bf408601fb721fe9b5c",
  "type": "report.ready",
  "created_at": "2026-10-05T09:02:11.000Z",
  "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "store_id": "0c1d2e3f-1111-4222-8333-444455556666",
  "severity": "info",
  "data": {
    "snapshot_id": "5a6b7c8d-9999-4aaa-8bbb-cccc0000dddd",
    "kind": "weekly",
    "cadence": "weekly",
    "schedule_source": "schedule",
    "locale": "pt-BR",
    "store_name": "My Store",
    "domain": "mystore.com",
    "period": { "start": "2026-09-28T09:00:00.000Z", "end": "2026-10-05T09:00:00.000Z" },
    "pdf_url": "https://…/reports/…pdf?token=…",
    "url": "https://app.proteside.com/compliance?tab=reports&snapshot=5a6b7c8d-9999-4aaa-8bbb-cccc0000dddd",
    "pending_reviews": 3,
    "review_due": 1,
    "open_alerts": 2,
    "open_alerts_by_severity": { "critical": 0, "high": 1, "medium": 1, "low": 0, "info": 0 },
    "summary_643": { "...": "..." },
    "summary_1161": { "...": "..." },
    "digest": { "...": "..." },
    "report": {
      "id": "5a6b7c8d-9999-4aaa-8bbb-cccc0000dddd",
      "kind": "weekly",
      "period_start": "2026-09-28T09:00:00.000Z",
      "period_end": "2026-10-05T09:00:00.000Z",
      "pdf_url": "https://…/reports/…pdf?token=…",
      "url": "https://app.proteside.com/compliance?tab=reports&snapshot=5a6b7c8d-9999-4aaa-8bbb-cccc0000dddd"
    },
    "store": { "name": "My Store", "domain": "mystore.com" }
  }
}
```

The `pdf_url` link is signed and valid for 7 days. It may be `null` if the PDF isn't available.

### test

```json
{
  "id": "evt_e4da3b7fbbce2345d7772b0674a318d5",
  "type": "test",
  "created_at": "2026-10-06T12:11:00.000Z",
  "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
  "store_id": null,
  "severity": "info",
  "data": {
    "message": "Test notification from Proteside",
    "channel": { "id": "a9b8c7d6-5555-4666-8777-888899990000", "name": "Production SIEM", "type": "webhook" }
  }
}
```

## Verify the signature
When the channel has a secret, each delivery includes:

```text
X-Proteside-Signature: t=1791277201,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

* `t` is the send time in Unix seconds (recomputed on every attempt).
* `v1` is the HMAC-SHA256, in hexadecimal, of `t` + `.` + the **raw body**, using the entire secret as the key,
  including the `whsec_` prefix.

To verify:

1. Read the **raw** body, before any JSON parsing. Re-serializing the JSON changes the bytes and breaks the signature.
2. Split out `t` and `v1` and check their format: `t` an integer, `v1` 64 hexadecimal characters.
3. Reject deliveries whose `t` is more than **300 seconds** off from your clock. Proteside doesn't enforce this
   limit: protecting against malicious replays is the receiver's responsibility.
4. Compute the expected HMAC and compare in constant time.

  **Node.js**

```js title="server.js"
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.PROTESIDE_WEBHOOK_SECRET; // "whsec_..."
const TOLERANCE_S = 300;

function verifySignature(rawBody, header, secret) {
  if (!header) return false;

  const parts = {};
  for (const item of header.split(',')) {
    const i = item.indexOf('=');
    if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim();
  }

  // 1. validate the format before any comparison
  if (!/^\d+$/.test(parts.t ?? '') || !/^[0-9a-f]{64}$/i.test(parts.v1 ?? '')) return false;

  // 2. time window against replays
  const t = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return false;

  // 3. HMAC-SHA256(secret, "t." + raw body), compared in constant time
  const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1, 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}

const app = express();
const seen = new Set(); // in production, use Redis or your database

// express.raw keeps the body as a Buffer, unparsed
app.post('/hooks/proteside', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature(req.body, req.get('X-Proteside-Signature'), SECRET)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString('utf8'));
  if (seen.has(event.id)) return res.sendStatus(200); // already processed
  seen.add(event.id);

  res.sendStatus(204); // respond quickly (under 8 s)...
  queueMicrotask(() => handleEvent(event)); // ...and process afterwards
});

function handleEvent(event) {
  console.log(event.type, event.data);
}

app.listen(3000);
```

  **Python**

```python title="app.py"
import hashlib
import hmac
import os
import re
import time

from flask import Flask, abort, request

SECRET = os.environ["PROTESIDE_WEBHOOK_SECRET"].encode()  # the entire "whsec_...", as UTF-8 bytes
TOLERANCE_S = 300
HEX64 = re.compile(r"^[0-9a-fA-F]{64}$")

app = Flask(__name__)
seen: set[str] = set()  # in production, use Redis or your database

def verify_signature(raw_body: bytes, header: str | None) -> bool:
    if not header:
        return False

    parts = {}
    for item in header.split(","):
        key, sep, value = item.partition("=")
        if sep:
            parts[key.strip()] = value.strip()

# 1. validate the format before any comparison
    t_raw, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t_raw.isdigit() or not HEX64.match(v1):
        return False

# 2. time window against replays
    t = int(t_raw)
    if abs(time.time() - t) > TOLERANCE_S:
        return False

# 3. HMAC-SHA256(secret, "t." + raw body), compared in constant time
    expected = hmac.new(SECRET, f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1.lower())

@app.post("/hooks/proteside")
def proteside_hook():
    raw = request.get_data()  # raw body, before parsing
    if not verify_signature(raw, request.headers.get("X-Proteside-Signature")):
        abort(401)

    event = request.get_json()
    if event["id"] in seen:
        return "", 200  # already processed
    seen.add(event["id"])

# queue the processing and respond in under 8 s
    return "", 204
```

### Rotate the secret
Send a new `secret` in `PATCH /webhooks/{id}` (or edit the **Signing secret** in the dashboard). The change applies
from the next delivery, with no overlap period: pending retries are also signed with the new secret. To avoid losing
events, make your receiver accept both secrets for a few minutes, rotate it in Proteside, and then remove the old one.

## Delivery and retries
* The first attempt goes out when the event happens.
* Your endpoint has **8 seconds** to respond. Only `2xx` responses count as success.
* **Redirects aren't followed**: a `301` or `302` counts as a failure. Register the final URL.
* On failure, Proteside retries until it completes **4 attempts**: the immediate one plus three more, roughly
  **1 minute**, **10 minutes** and **60 minutes** after the previous failure. Retries run in 5-minute cycles, so they
  may be delayed a few minutes beyond these intervals.
* After the fourth failure, the delivery is marked **Failed** and isn't resent. The channel isn't deactivated
  automatically.
* If the channel is deactivated when a retry is due, the delivery fails without being resent.
* There's no ordering guarantee between events.

> **It may arrive more than once**
>
> If your endpoint processes the event but takes longer than 8 seconds to respond, Proteside counts it as a failure
> and sends it again. Deduplicate by the event `id` (`evt_…`), which stays the same across retries, or by the
> `X-Proteside-Delivery` header. Respond `2xx` quickly and process in the background.

The history of the last 50 deliveries (event, status, attempts, HTTP code and error) is in
**Settings → Notifications**, in the **Delivery history** card, for up to 90 days. The API doesn't expose the history
or let you resend a delivery manually.

## Test the webhook
In the dashboard, click **Test connection** on the channel's card. Through the API:

```bash
curl -s -X POST "https://app.proteside.com/api/v1/webhooks/a9b8c7d6-5555-4666-8777-888899990000/test" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"
```

```json
{ "id": "a9b8c7d6-5555-4666-8777-888899990000", "delivered": false, "error": "http_404" }
```

The test sends a signed `test` event, with a single attempt. It ignores the event and severity filters and is sent
even if the channel is deactivated.

> **Check the delivered field**
>
> `POST /webhooks/{id}/test` responds `200` even when delivery fails. Check `delivered` and, if it's `false`, the
> reason in `error`: the HTTP status code received (`http_<status>`), `timeout` or a network message.

## Slack, Microsoft Teams and email
If you only want notifications for people, you don't need your own endpoint:

* **Slack**: create an Incoming Webhook in Slack and register its URL with `"format": "slack"` in the API, or with the
  **Slack** type in the dashboard. Proteside sends a formatted message with a summary of the event and a button to
  open it in the dashboard.
* **Microsoft Teams**: the same with `"format": "teams"` or the **Teams** type. The message is an Adaptive Card.
* **Email**: dashboard only (**Email** type, up to 5 recipients). Every store starts with an "E-mail (padrão)"
  channel (the default email channel) for the owner's email address.

> **Note**
>
> Slack and Teams messages have fixed English text. Email channels only receive `alert.created`, `report.ready` and
> `test`, even if other events are checked: `integrity.changed`, `header.changed` and `sdk.silent` notifications don't
> arrive by email. For those, use a webhook, Slack or Teams.

## Next steps
- [Recipes](https://docs.proteside.com/en/docs/api/recipes#criar-um-webhook-e-disparar-um-teste): Create a webhook and send a test, step by step.
- [Partners](https://docs.proteside.com/en/docs/api/partners): Webhooks in child organizations.
- [Reference: webhooks](https://docs.proteside.com/en/docs/api/reference/webhooks/createWebhook): All the create and update fields.
