Receive real-time notifications for grant and token lifecycle events.
Overview
The webhooks sub-client lets you create, list, and delete webhook endpoints. When events occur (e.g. a grant is created or revoked), Grantex sends an HTTP POST to your registered URLs with a signed payload.
const webhook = await grantex.webhooks.create({ url: 'https://yourapp.com/webhooks/grantex', events: ['grant.created', 'grant.revoked', 'token.issued'],});// Store the secret for verifying payloadsconsole.log(webhook.secret);
webhooks.create()
Create a new webhook endpoint. The response includes a secret for verifying payload signatures — store it securely, as it is only returned once.
The HMAC signing secret. Only returned on creation.
string
ISO 8601 creation timestamp.
webhooks.list()
List all webhook endpoints for your organization.
const result = await grantex.webhooks.list();for (const webhook of result.webhooks) { console.log(`${webhook.id}: ${webhook.url} (${webhook.events.join(', ')})`);}
Response: ListWebhooksResponse
WebhookEndpoint[]
Array of webhook endpoint objects (without secrets).
webhooks.delete()
Delete a webhook endpoint.
await grantex.webhooks.delete('wh_01HXYZ...');// Returns void -- the endpoint is removed
Parameters
string
required
The webhook endpoint ID to delete.
Response
Returns void.
Verifying webhook signatures
The SDK exports a verifyWebhookSignature() function to verify that incoming webhook payloads were sent by Grantex. The function uses HMAC-SHA256 with timing-safe comparison.
Import
import { verifyWebhookSignature } from '@grantex/sdk';
The webhook secret returned when the endpoint was created.
Response
Returns true if the signature is valid, false otherwise.
Always use the raw request body for verification. Parsing the JSON before verifying will change the byte representation and cause signature mismatches.