Webhooks

while.webhooks.create({
  url: "https://your-agent.com/webhook",
  events: ["deployment.failed", "error.detected", "uptime.down"],
  secret: "optional-signing-secret"  // auto-generated if omitted
})

POST /api/webhooks
Authorization: Bearer whl_your_key
Content-Type: application/json

{
  "url": "https://your-agent.com/webhook",
  "events": ["deployment.failed", "error.detected"],
  "secret": "optional-signing-secret"
}

A signing secret (whsec_...) is returned on creation. Store it securely — it cannot be retrieved again.

While sends a POST request to your webhook URL with a JSON payload. Every payload includes the event type, tenant context, and event-specific data.

POST https://your-agent.com/webhook
Content-Type: application/json
X-While-Signature: sha256=a1b2c3...

{
  "type": "deployment.failed",
  "tenantId": "tenant_abc",
  "projectId": "proj_xyz",
  "environmentId": "env_stg",
  "payload": {
    "deploymentId": "dep_123",
    "status": "failed",
    "error": "Build failed: npm install exited with code 1",
    "commitSha": "abc123"
  },
  "timestamp": "2026-03-06T14:30:00.000Z"
}

Every webhook request includes an X-While-Signature header containing an HMAC-SHA256 signature of the request body. Verify this to ensure the request came from While.

import crypto from "crypto";

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return signature === `sha256=${expected}`;
}

// Usage in your webhook handler:
app.post("/webhook", (req, res) => {
  const sig = req.headers["x-while-signature"];
  if (!verifyWebhook(JSON.stringify(req.body), sig, "whsec_your_secret")) {
    return res.status(401).send("Invalid signature");
  }
  // Process the event...
});

Use the test tool to send a sample payload to your webhook URL and verify it works.

// Via MCP
while.webhooks.test({ id: "webhook_abc" })

// Via REST API
POST /api/webhooks/:id/test
Authorization: Bearer whl_your_key

The test sends a sample webhook.test event to the URL. Check the response status to confirm your endpoint is receiving and processing events correctly.