Webhooks
Register a webhook
Section titled “Register a webhook”POST /v1/webhooks| Field | Type | Required | Description |
|---|---|---|---|
url | string | ✅ | HTTPS endpoint URL |
events | array | Event types to subscribe to |
Available events:
recording.completed— A user has recorded their nameinvite.delivered— Invitation email was deliveredinvite.bounced— Invitation email bounced
curl -X POST https://api.nouncify.com/v1/webhooks \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.com/webhooks/nouncify", "events": ["recording.completed"] }'Response 201 Created
{ "id": "webhook-uuid", "url": "https://your-app.com/webhooks/nouncify", "secret": "whsec_...", "events": ["recording.completed"], "is_active": true, "created_at": "2026-04-01T00:00:00Z"}Webhook payloads
Section titled “Webhook payloads”recording.completed
Section titled “recording.completed”{ "event": "recording.completed", "timestamp": "2026-04-01T00:00:00Z", "data": { "collection_id": "collection-uuid", "user_id": "user-uuid", "recording_id": "recording-uuid", "play_link": "https://api.nouncify.com/p/HkJ3mN8x", "duration_seconds": 2.4, "recorded_at": "2026-04-01T00:00:00Z" }}invite.delivered
Section titled “invite.delivered”{ "event": "invite.delivered", "timestamp": "2026-04-01T00:00:00Z", "data": { "email": "priya@company.com", "first_name": "Priya", "last_name": "Patel", "batch_id": "batch-uuid" }}invite.bounced
Section titled “invite.bounced”{ "event": "invite.bounced", "timestamp": "2026-04-01T00:00:00Z", "data": { "email": "invalid@company.com", "first_name": "Unknown", "batch_id": "batch-uuid", "error_code": 406, "error_message": "Inactive recipient" }}Verifying signatures
Section titled “Verifying signatures”All webhooks include an X-Nouncify-Signature header containing an HMAC-SHA256 signature.
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) );}List webhooks
Section titled “List webhooks”GET /v1/webhooksDelete a webhook
Section titled “Delete a webhook”DELETE /v1/webhooks/{webhook_id}Retry policy
Section titled “Retry policy”Failed webhook deliveries are retried up to 3 times with exponential backoff:
- Attempt 1: immediate
- Attempt 2: after 30 seconds
- Attempt 3: after 2 minutes
After 10 consecutive failures, the webhook is automatically disabled.