Webhooks

Webhooks allow TrueGrade to push real-time event notifications to any external system that accepts HTTP POST requests. Use webhooks to trigger automations, update external dashboards, or sync data with your own systems.

Supported Events

Creating a Webhook

Navigate to Administration → Integrations → Webhooks → Add Webhook:

1. Endpoint URL — the HTTPS URL of your receiving server
2. Secret — a random string used for HMAC signing (generate one or enter your own)
3. Events — select which event types to send to this endpoint
4. Active — toggle to enable/disable without deleting

Request Format

TrueGrade sends a JSON POST request for each event:

{
  "id": "wh_01hwz2k9m3x8y4b6c7d",
  "event": "document.submitted",
  "timestamp": "2026-04-22T14:32:00Z",
  "organization_id": "org_01hwz2...",
  "project_id": "proj_01hwz2...",
  "payload": {
    "subcontractor_id": "sub_01hwz2...",
    "subcontractor_name": "Acme Insulation LLC",
    "document_type": "certificate_of_insurance",
    "document_id": "doc_01hwz2..."
  }
}

Verifying Signatures

Every webhook request includes an X-TrueGrade-Signature header containing an HMAC-SHA256 signature. Verify it on your server to confirm the request came from TrueGrade:

import { createHmac, timingSafeEqual } from 'crypto'
 
function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  )
}

Always use timingSafeEqual (or equivalent constant-time comparison) to prevent timing attacks.

Delivery and Retries

• TrueGrade expects a 2xx response within 10 seconds
• If no 2xx is received, the delivery is retried up to 5 times with exponential backoff (1m, 5m, 15m, 1h, 4h)
• After 5 failed attempts, the webhook is marked Failed and no further retries occur
• Failed deliveries are visible in Administration → Integrations → Webhooks → [Webhook] → Delivery Log

Delivery Log

Every delivery attempt is logged with:

• Event ID and type
• HTTP status code returned by your server
• Response body (first 500 characters)
• Timestamp
• Retry number

You can manually retry a failed delivery from the log view.