Skip to content
Back to Nouncify

Webhooks

POST /v1/webhooks
FieldTypeRequiredDescription
urlstring✅HTTPS endpoint URL
eventsarrayEvent types to subscribe to

Available events:

  • recording.completed — A user has recorded their name
  • invite.delivered — Invitation email was delivered
  • invite.bounced — Invitation email bounced
Terminal window
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"
}
{
"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"
}
}
{
"event": "invite.delivered",
"timestamp": "2026-04-01T00:00:00Z",
"data": {
"email": "priya@company.com",
"first_name": "Priya",
"last_name": "Patel",
"batch_id": "batch-uuid"
}
}
{
"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"
}
}

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)
);
}
GET /v1/webhooks
DELETE /v1/webhooks/{webhook_id}

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.