Webhooks Guide

Webhooks let your application receive real-time HTTP callbacks when events occur.

Setup

1. Create an endpoint

Create an HTTPS endpoint on your server that accepts POST requests:

// Express.js example
app.post('/webhooks/nouncify', (req, res) => {
  const signature = req.headers['x-nouncify-signature'];
  const body = JSON.stringify(req.body);

  if (!verifySignature(body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;

  switch (event) {
    case 'recording.completed':
      // Update your database with the play link
      await db.users.update(data.user_id, {
        pronunciation_url: data.play_link
      });
      break;
  }

  res.status(200).send('OK');
});

2. Register the webhook

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"]
  }'

3. Store the secret

The response includes a secret field. Store it securely — you’ll use it to verify webhook signatures.

Verifying signatures

Every webhook includes an X-Nouncify-Signature header with an HMAC-SHA256 signature.

Node.js

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)
  );
}

Python

import hmac
import hashlib

def verify_signature(payload: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Event reference

recording.completed

Sent when a user finishes recording their name.

{
  "event": "recording.completed",
  "timestamp": "2026-04-01T00:00:00Z",
  "data": {
    "collection_id": "collection-uuid",
    "user_id": "user-uuid",
    "email": "priya@company.com",
    "first_name": "Priya",
    "last_name": "Patel",
    "play_link": "https://api.nouncify.com/p/HkJ3mN8x",
    "recorded_at": "2026-04-01T00:00:00Z"
  }
}

Retry policy

Attempt	Delay
1	Immediate
2	30 seconds
3	2 minutes

After 10 consecutive failures, the webhook is automatically disabled. Re-enable it from the Developer Dashboard.