Destinations

List destinations

GET /api/v1/destinations

Returns all webhook destinations for the authenticated user.

Response

{
  "data": [
    {
      "id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f67",
      "url": "https://example.com/webhooks/varen",
      "events": ["change.breaking", "monitor.failed"],
      "active": true,
      "created_at": "2026-02-10T09:00:00Z"
    }
  ]
}

Create destination

POST /api/v1/destinations

Requires Pro plan.

Registers a new webhook destination. The signing secret is returned only once in the response — store it securely.

Request body

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL to receive webhook events
`events`	string[]	Yes	Event types to subscribe to (see below)

Example

curl -X POST https://api.varen.dev/v1/destinations \
  -H "Authorization: Bearer vk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/varen",
    "events": ["change.breaking", "change.detected"]
  }'

Response

{
  "data": {
    "id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f67",
    "url": "https://example.com/webhooks/varen",
    "events": ["change.breaking", "change.detected"],
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "active": true,
    "created_at": "2026-02-10T09:00:00Z"
  }
}

The secret field is only returned when creating a destination. Store it immediately — it cannot be retrieved later.

Delete destination

DELETE /api/v1/destinations/:id

Requires Pro plan.

Removes a webhook destination. Returns 204 No Content on success.

Event types

Event	Description
`change.detected`	Any change detected on a monitored API
`change.breaking`	Breaking change detected
`monitor.failed`	Monitor scan failed (e.g., docs unreachable)
`monitor.recovered`	Monitor recovered from failure state
`monitor.scan_completed`	Scan completed successfully

Webhook payload

All webhook deliveries include the following headers:

Header	Description
`X-Varen-Signature`	HMAC-SHA256 signature of the payload: `sha256=<hmac>`
`X-Varen-Event`	Event type (e.g., `change.breaking`)
`Content-Type`	`application/json`

Example payload for `change.breaking`

{
  "event": "change.breaking",
  "timestamp": "2026-03-15T14:30:00Z",
  "data": {
    "change_id": "b3f1a2c4-5d6e-7f89-0a1b-2c3d4e5f6789",
    "api_name": "Stripe API",
    "classification": "BREAKING",
    "severity": "critical",
    "endpoint": "POST /v1/charges",
    "description": "The /v1/charges endpoint has been removed. Use /v1/payment_intents instead.",
    "detected_at": "2026-03-15T14:30:00Z",
    "dashboard_url": "https://varen.dev/dashboard/changes/b3f1a2c4-5d6e-7f89-0a1b-2c3d4e5f6789"
  }
}

Verifying webhook signatures

Use the signing secret from destination creation to verify that webhook payloads are authentic.

Node.js

import crypto from "node:crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  const actual = signature.replace("sha256=", "");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(actual, "hex")
  );
}

// In your webhook handler:
const payload = JSON.stringify(req.body);
const signature = req.headers["x-varen-signature"];
const isValid = verifyWebhook(payload, signature, process.env.VAREN_WEBHOOK_SECRET);

if (!isValid) {
  return res.status(401).json({ error: "Invalid signature" });
}

On this page