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 payloads
console.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.
const webhook = await grantex.webhooks.create({
url: 'https://yourapp.com/webhooks/grantex',
events: ['grant.created', 'grant.revoked'],
});
console.log(webhook.id); // 'wh_01HXYZ...'
console.log(webhook.url); // 'https://yourapp.com/webhooks/grantex'
console.log(webhook.events); // ['grant.created', 'grant.revoked']
console.log(webhook.secret); // 'whsec_01HXYZ...' -- store securely!
console.log(webhook.createdAt); // '2026-02-28T12:00:00Z'
Parameters
The HTTPS URL to receive webhook events.
events
WebhookEventType[]
required
The events to subscribe to.
Event types
| Event | Description |
|---|
grant.created | A new grant has been issued |
grant.revoked | A grant has been revoked |
token.issued | A grant token has been issued |
Response: WebhookEndpointWithSecret
Unique webhook endpoint identifier.
The subscribed event types.
The HMAC signing secret. Only returned on creation.
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
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
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';
Usage
import { verifyWebhookSignature } from '@grantex/sdk';
import express from 'express';
const app = express();
app.post('/webhooks/grantex', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-grantex-signature'] as string;
const secret = process.env.GRANTEX_WEBHOOK_SECRET;
const isValid = verifyWebhookSignature(req.body, signature, secret);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body.toString());
console.log(`Received event: ${event.type}`);
// Handle the event...
res.status(200).send('OK');
});
Parameters
The raw request body as received from Grantex.
The value of the X-Grantex-Signature header.
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.
