Goa-gel-fullstack/Documentation/developers/webhooks.md

# Webhooks

## Overview

The platform sends webhook notifications for key events. Configure webhook endpoints to receive real-time updates.

## Configuration

Register webhook endpoint:

```http
POST /webhooks
Authorization: Bearer <token>

{
  "url": "https://your-system.com/webhook",
  "events": ["application.approved", "certificate.issued"],
  "secret": "your-webhook-secret"
}
```

## Event Types

| Event | Trigger |
|-------|---------|
| `application.submitted` | New application received |
| `application.approved` | Application approved |
| `application.rejected` | Application rejected |
| `application.returned` | Returned for corrections |
| `certificate.issued` | License NFT minted |
| `certificate.revoked` | License revoked |

## Payload Format

```json
{
  "event": "application.approved",
  "timestamp": "2026-02-09T10:00:00Z",
  "data": {
    "applicationId": "APP-2026-00001",
    "licenseType": "TRADE_LICENSE",
    "applicantId": "DL-12345678"
  }
}
```

## Signature Verification

Verify webhook authenticity using HMAC-SHA256:

```javascript
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

Header: `X-Webhook-Signature: sha256=<signature>`

## Retry Policy

Failed deliveries (non-2xx response) are retried:
- 1st retry: 1 minute
- 2nd retry: 5 minutes
- 3rd retry: 30 minutes
- 4th retry: 2 hours
- 5th retry: 24 hours

After 5 failures, webhook is disabled. Re-enable via API.