Graphoid Webhooks Reference

How Webhooks Work

When an event occurs in Graphoid, we send a POST request to your configured endpoint with a JSON payload describing what happened.

Event occurs
e.g. lead.won

Graphoid sends
HTTPS POST

Your endpoint
receives payload

Return 200 OK
within 10 seconds

Your endpoint must respond with a 2xx status within 10 seconds. Any other response triggers our retry mechanism.

Setup Guide

Register a webhook endpoint in 3 steps:

1

Register your endpoint

Go to Settings → Developer → Webhooks → Add Endpoint, or use the API:

curl

curl -X POST https://api.graphoid.io/v2/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://yourapp.com/webhooks/graphoid",
    "events": ["lead.won", "ticket.escalated", "ai.analysis.complete"],
    "active": true
  }'

2

Verify the signature

Every webhook request includes a X-Graphoid-Signature header. Always verify it before processing:

node.js — express

const crypto = require('crypto');

app.post('/webhooks/graphoid', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-graphoid-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (sig !== `sha256=${expected}`) {
    return res.status(401).send('Unauthorized');
  }

  const event = JSON.parse(req.body);
  // process event...
  res.status(200).send('OK');
});

3

Respond quickly, process async

Return a 200 OK immediately, then process the event asynchronously (queue, worker, etc.). Slow endpoints may be temporarily disabled after repeated timeouts.

Event Catalog

Subscribe to any combination of these events per endpoint.

Sales & Leads

lead.created lead.updated lead.won lead.lost lead.reassigned lead.stage_changed

Tickets & Support

ticket.created ticket.resolved ticket.escalated ticket.sla_breached ticket.reopened

HR & Attendance

attendance.punch_in attendance.punch_out attendance.absent attendance.anomaly_detected

Billing & Finance

invoice.created invoice.overdue payment.received contract.renewal_due contract.expired

AI & Analytics

ai.analysis.complete ai.risk.critical ai.forecast.updated ai.health_score.changed

Payload Format

All events share a common envelope structure:

json — lead.won example

{
  "id": "evt_9pQrXy2k...",
  "event": "lead.won",
  "timestamp": "2026-04-03T14:22:00Z",
  "workspace_id": "ws_7hGt...",
  "api_version": "v2",
  "data": {
    "lead": {
      "id": "lead_4mNp...",
      "name": "Acme Corp",
      "value": 45000,
      "closed_by": "user_8x2k...",
      "closed_at": "2026-04-03T14:22:00Z"
    }
  }
}

Signature Verification

Every request is signed with your webhook secret using HMAC-SHA256. Always verify before processing.

Never skip signature verification. Without it, anyone can send fake events to your endpoint.

The signature is in the X-Graphoid-Signature header, formatted as sha256=<hex_digest>. Use a constant-time comparison to prevent timing attacks.

Retry Policy

If your endpoint returns a non-2xx response or times out, Graphoid will retry with exponential backoff:

Attempt	Delay	Total elapsed
1st retry	5 minutes	5 min
2nd retry	30 minutes	35 min
3rd retry	2 hours	~2.5 hrs
Final retry	8 hours	~10 hrs

After 4 failed attempts, the event is marked as failed and logged in your dashboard. Endpoints that fail >10% of deliveries are automatically disabled with an alert.

Testing Webhooks

Use the dashboard to send test payloads, or trigger test events via the API:

curl — send test event

curl -X POST https://api.graphoid.io/v2/webhooks/{id}/test \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "event": "lead.won" }'

For local development, use a tunnel tool to expose your localhost and test webhooks against it.