---
title: "Webhook Delivery"
description: "Deliver compact CloudEvents when intelligence reports are published"
canonical: https://y2.dev/docs/delivery/webhooks/
---

Delivery

# Webhook Delivery

Deliver compact CloudEvents when intelligence reports are published

Webhook delivery sends CloudEvents 1.0 notifications to an HTTPS endpoint after report publication. It requires Lite, Pro, or Elite. Configure a secret to sign requests.

A webhook notification is compact. It identifies the report and provides API links. It does not embed the full HTML report or all source records.

## Create an endpoint in Y2

You do not need an API key when configuring webhooks in the app.

### Open Webhooks

In an active paid workspace, go to **Developers → Webhooks**.

### Create a configuration

Enter a name. Enter the public endpoint URL. Production webhook URLs must use HTTPS. Localhost, loopback, private-network, link-local, and other blocked addresses are rejected.

### Add verification and authentication

Generate or enter an optional signing secret. You can also add custom string headers, such as an authorization token for your endpoint.

`Host`, `Content-Length`, and `Content-Type` cannot be supplied as custom headers. Y2's own delivery headers take precedence over custom values.

### Save and test

Create the webhook. Select **Test Webhook**. The test sends a `dev.y2.webhook.test.v1` CloudEvent and waits up to 10 seconds for a response.

### Assign it to a profile

Open **InfoOps → My Profiles → Delivery Preferences**. Choose **Webhook**. Select the active configuration. Save the preferences.

Selecting **Webhook** replaces email and SMS for that subscription. There is no combined Email + Webhook delivery method.

## Receive a report event

Report deliveries use `Content-Type: application/cloudevents+json` and the event type `dev.y2.report.generated.v1`.

```
{
  "specversion": "1.0",
  "id": "y2mexampleeventid",
  "source": "https://api.y2.dev/api/v1/profiles/prf_0123456789abcdef01234567",
  "type": "dev.y2.report.generated.v1",
  "subject": "reports/rpt_0123456789abcdef01234567",
  "time": "2026-07-21T12:00:00.000Z",
  "datacontenttype": "application/json",
  "dataschema": "https://api.y2.dev/schemas/events/report-generated-v1.json",
  "data": {
    "report": {
      "id": "rpt_0123456789abcdef01234567",
      "profileId": "prf_0123456789abcdef01234567",
      "summary": "Concise report summary...",
      "status": "published",
      "generatedAt": "2026-07-21T11:59:48.000Z",
      "language": "en",
      "intelligence": {
        "signalCount": 4,
        "graphNodeCount": 12
      },
      "audio": {
        "status": "available",
        "durationSeconds": 318
      }
    },
    "subscription": {
      "id": "sub_0123456789abcdef01234567"
    },
    "links": {
      "report": "https://api.y2.dev/api/v1/reports/rpt_0123456789abcdef01234567",
      "markdown": "https://api.y2.dev/api/v1/reports/rpt_0123456789abcdef01234567?format=markdown",
      "sources": "https://api.y2.dev/api/v1/reports/rpt_0123456789abcdef01234567?include=sources",
      "signals": "https://api.y2.dev/api/v1/reports/rpt_0123456789abcdef01234567/signals",
      "graph": "https://api.y2.dev/api/v1/reports/rpt_0123456789abcdef01234567/graph",
      "audio": "https://api.y2.dev/api/v1/reports/rpt_0123456789abcdef01234567/audio"
    }
  }
}
```

`summary` can be `null`, and audio can be marked `unavailable`. Following a link can require an appropriately scoped API key or the endpoint's documented x402 flow.

## Request headers

Prop

Type

## Verify the signature

Compute HMAC-SHA256 over the exact raw request body bytes using the configured secret. Prefix the hex digest with `sha256=`. Compare it with `X-Y2-Signature` in constant time.

```
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyY2Webhook(rawBody, headers, secret) {
  const supplied = headers["x-y2-signature"] ?? "";
  const timestamp = Number(headers["x-y2-timestamp"] ?? 0);
  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - timestamp);

  if (!timestamp || ageSeconds > 300) return false;

  const expected = `sha256=${createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex")}`;
  const suppliedBytes = Buffer.from(supplied);
  const expectedBytes = Buffer.from(expected);

  return (
    suppliedBytes.length === expectedBytes.length &&
    timingSafeEqual(suppliedBytes, expectedBytes)
  );
}
```

Use the raw bytes before JSON parsing. Re-serializing an object can change the signed body. Keep your own replay window policy and deduplicate with `Idempotency-Key` or `X-Y2-Event-Id`.

A secret is optional in the configuration form. If you omit it, Y2 does not send `X-Y2-Signature`. Secure the endpoint with a custom authorization header or another control.

## Acknowledge deliveries safely

The delivery request has a 10-second timeout. Return `2xx` only after storing or durably queuing the event. Process longer tasks asynchronously.

```
app.post("/y2/webhook", rawBodyMiddleware, async (request, response) => {
  if (!verifyY2Webhook(request.rawBody, request.headers, process.env.Y2_WEBHOOK_SECRET)) {
    return response.sendStatus(401);
  }

  await queue.put({
    id: request.headers["x-y2-event-id"],
    event: JSON.parse(request.rawBody.toString("utf8")),
  });

  return response.sendStatus(202);
});
```

Network errors, timeouts, HTTP 408/429, and 5xx responses can retry up to five total attempts. Retry delays are 5 seconds, 30 seconds, 5 minutes, and 30 minutes. Other HTTP rejections pause the destination immediately. Five consecutive failures also pause it. A successful delivery resets the failure count. Retries do not regenerate reports.

The owner receives a warning when temporary failures begin and another email when delivery pauses. Reports, configuration, and history remain available. Other destinations continue independently.

### Recover a paused destination

1. Save any endpoint, secret, or header changes.
2. Run **Test Webhook**.
3. After a successful test, enable delivery within 15 minutes.
4. Use **Delivery history and replay** to resend a retained failed event if needed.

Tests work while paused. Configuration changes or a new production failure invalidate the test. Replay keeps the original payload and event ID. Deduplicate it at the receiver. Enabling delivery does not send the backlog automatically.

## Manage configurations

- Editing a masked webhook leaves its existing secret unchanged when the secret field is blank.
- Activating a paused webhook requires a current successful test and resets its failure count.
- An inactive webhook cannot be assigned for delivery.
- A configuration cannot be deleted while any subscription references it. Reassign those profiles first.
- The app exposes 30-day success/failure statistics, last-use time, subscription count, and current consecutive failures.

You can also manage configurations through the public API. API-key requests use the `webhooks:manage` scope. Creating new API keys requires Pro or Elite, while webhook delivery itself is available on Lite.

## Next steps

[Webhook API guide](https://y2.dev/docs/api/webhooks): Review management endpoints and integration boundaries.

[Generated webhook reference](https://y2.dev/docs/api/reference/webhooks): Inspect canonical request and response schemas.

[Reports API](https://y2.dev/docs/api/reports): Retrieve report content linked by an event.
