Outbound webhooks

Vaks PM · Integration guide · Webhooks · July 2026

What it does — and what it does not

• It is outbound only. Vaks PM calls you. Nothing here opens an inbound path into your instance, so this works from a fully private deployment provided it can reach your receiver.
• Delivery is at-least-once, not exactly-once. Retries mean your receiver can see the same delivery twice. Deduplicate on the delivery identifier — see step 2.
• Order is not guaranteed. Dispatch is fire-and-forget and retries reorder freely. Never infer sequence from arrival order; use the timestamps in the payload.
• Some actions fire more than one event. Completing a task emits both task.updated and task.completed. A receiver subscribed to everything will see both.
• No licence required. Webhooks are available on every plan.

Events you can subscribe to

Twenty-seven events, plus the wildcard * which subscribes to all of them — including any added in future versions.

Prerequisites

Step 1 — Create the endpoint

Open Admin → Integrations → Webhooks → Endpoints and press New webhook.

Step 2 — Verify the signature

Every request carries an HMAC-SHA256 signature of the body, computed with your webhook's secret. Verifying it is what makes the endpoint safe to expose: without it, anyone who guesses your URL can post fake events.

Two details decide whether your implementation is correct:

• Sign the raw body, exactly as received. Parsing the JSON and re-serialising it changes the bytes and the signature will never match. Capture the raw body before your framework parses it.
• Compare in constant time, not with ==, so the comparison cannot be used as a timing oracle.

// Node.js / Express — note express.raw, not express.json
const crypto = require('crypto');

app.post('/vaks-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected =
    'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const got = req.get('X-Vaks-Signature') || '';

  const a = Buffer.from(expected), b = Buffer.from(got);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString('utf8'));
  // Deduplicate: the same deliveryId may arrive more than once.
  if (alreadyHandled(req.get('X-Vaks-Delivery'))) return res.status(200).end();

  handle(event);
  res.status(200).end();   // answer 2xx fast; do the work asynchronously
});

Step 3 — Test

Press Send test on the webhook's row. This sends a ping event immediately, regardless of which events you subscribed to, so it always works as a connectivity check.

Then open Recent deliveries below the list and confirm the row reads SUCCESS with a 2xx response. If it does not, expand Details — the error, the exact payload sent, and your receiver's response body are all recorded there. That panel is the single most useful debugging tool on this page.

Payload & headers

In raw format, every request has the same envelope, with the event-specific data nested under payload:

{
  "event": "task.created",
  "deliveryId": "9f1c…",
  "organizationId": "…",
  "at": "2026-07-19T21:04:11.482Z",
  "payload": { }
}

Payload shapes vary by event and are best discovered from a real delivery: subscribe, trigger the action, and read the recorded payload in the delivery log. Build your receiver defensively — treat fields as optional and ignore what you do not recognise, since payloads gain fields between versions.

Retries & failure

• Success is any HTTP 2xx. Everything else — 3xx, 4xx, 5xx, timeout, DNS failure — is a failure.
• Timeout is 10 seconds per attempt. Answer immediately and do your processing asynchronously; a slow receiver produces retries and duplicates.
• 5 attempts per delivery, with exponential backoff starting at 5 seconds.
• Redirects are followed, up to 3 hops, each one re-checked against the safety rules.

Microsoft Teams format

Choosing Teams (Adaptive Card) replaces the JSON envelope with a Teams message wrapping an Adaptive Card. The body Vaks PM sends looks like this:

{
  "type": "message",
  "attachments": [{
    "contentType": "application/vnd.microsoft.card.adaptive",
    "content": { /* an Adaptive Card: title, headline, up to 8 facts */ }
  }]
}

That shape is exactly what Teams expects. The card shows a title for the event, a one-line headline drawn from the payload, and up to eight facts when present: status, priority, assignee, author, due date, team, skill and project. There are two ways to get it into a channel — pick one.

Option A — Teams Workflows / Power Automate (recommended)

This is Microsoft's current path and the one that will keep working. Microsoft is retiring the older incoming-webhook connectors (Option B), so prefer this for anything new.

1. In the target Teams channel, open the … menu → Workflows (or go to Power Automate directly). Choose the template "Post to a channel when a webhook request is received".
2. Pick the team and channel to post into, and create the flow. Its trigger — "When a Teams webhook request is received" — generates a callback URL. Copy it.
3. In Vaks PM, create a webhook (or edit one): set Payload format to Teams (Adaptive Card), paste the callback URL into URL, and tick the events you want.
4. Back in the flow, make sure the posting action receives the Adaptive Card from the request body. Vaks PM sends the card under attachments[0].content; if the template does not already reference it, point the "Post card in a chat or channel" action at that path.
5. Save the flow, then press Send test on the webhook in Vaks PM. A card should appear in the channel within a few seconds. If it does not, open Recent deliveries — a 2xx with no card usually means the flow ran but the card field was not wired to attachments[0].content.

Option B — Teams incoming webhook (simplest, being retired)

If your tenant still allows incoming-webhook connectors, this needs no flow at all — the body Vaks PM sends is exactly what the connector expects.

1. In the channel, … menu → Connectors → Incoming Webhook → Configure. Name it, optionally set an icon, and Create.
2. Copy the generated URL — it is on ….webhook.office.com.
3. In Vaks PM, create the webhook with Payload format = Teams (Adaptive Card) and that URL. Send test; the card posts directly.

Scope & delegation

A webhook's scope decides which events reach it:

Delegation is controlled by Who can create a webhook, under Admin → Integrations → Webhooks → Governance:

• Project manager (default) — portfolio managers, plus the project manager of the project concerned.
• Portfolio manager — portfolio managers only.
• Admin — nobody but administrators.

Where allowed, project managers reach it from the project's Manage → Integrations tab, which only appears when their role permits it. Scope is forced server-side to their own project, so a delegated user cannot widen it — not at creation, and not by editing afterwards.

Allowlists & SSRF protection

Because a webhook sends your data to an address someone typed in, destinations are checked. Two settings under Governance tighten this, and both are worth turning on before delegating webhook creation to project managers:

Independently of any setting, internal targets are always refused: localhost, .local, .internal, and private, loopback or link-local address ranges. This is checked twice — when the URL is saved and again at send time, with an actual DNS resolution, which also defeats a hostname that only resolves to a private address later.

Delivery log

Recent deliveries, below the endpoint list, records every attempt: status and response code, event, target webhook, when it was queued, and how many attempts it took. Expanding a row shows the error, the payload sent and your receiver's response body (first 1000 characters).

A failed delivery can be replayed with Retry. It reuses the stored payload and the same delivery identifier, so a receiver that deduplicates correctly will recognise it — but the timestamp and signature are recomputed. The destination is re-checked against current governance first, so a retry to a now-forbidden address is refused.

Troubleshooting

What is logged

Creating, editing, deleting a webhook and rotating its secret are all audited at critical severity — a webhook is a data-exfiltration path, so changes are treated as security events. You will find them under Admin → Security & Compliance → Audit log, with the actor and the target.

Related: all integrations · operations for backup alerting, which uses the backup.failed event.