Webhooks

Receive real-time notifications when events occur in your Nur account.

Overview

Webhooks allow your application to receive real-time HTTP callbacks when specific events happen in your Nur account. Instead of polling the API to check the status of long-running tasks, you can register a webhook URL and Nur will send a POST request to that URL whenever an event occurs.

Common use cases for webhooks include:

Dubbing job completed

Get notified when an AI dubbing job finishes processing so you can deliver the dubbed content immediately.

Voice clone ready

Receive an alert as soon as a custom voice clone has been trained and is ready for use.

Agent session ended

Track when a voice agent session concludes to log analytics or trigger follow-up workflows.

Music generation finished

Know the moment a music track has been generated and is available for download.

Setup

To start receiving webhooks, register a webhook endpoint by sending a POST request to /v1/webhooks/create. Your endpoint must be a publicly accessible HTTPS URL that returns a 2xx status code.

curl -X POST https://api.nur.ai/v1/webhooks/create \
  -H "Authorization: Bearer nur_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/nur",
    "events": [
      "dubbing.completed",
      "voice.clone.completed",
      "agent.session.ended"
    ],
    "secret": "whsec_your_signing_secret"
  }'

Tip: Signing Secret

The secret parameter is optional but strongly recommended. When provided, Nur will sign every webhook payload with this secret so you can verify the request originated from Nur.

Events

Subscribe to specific events to only receive the notifications you need. The following events are available:

Event	Description
dubbing.completed	A dubbing job has finished processing successfully.
dubbing.failed	A dubbing job has failed due to an error.
voice.clone.completed	A voice clone has been trained and is ready for use.
voice.clone.failed	A voice cloning request has failed.
agent.session.started	A voice agent session has begun with a user.
agent.session.ended	A voice agent session has concluded.
music.generation.completed	A music generation task has finished and the track is available.

Payload Format

Every webhook delivery sends a JSON POST request to your registered URL. The payload follows a consistent structure across all event types:

{
  "id": "evt_abc123def456",
  "event": "dubbing.completed",
  "data": {
    "job_id": "dub_789xyz",
    "source_language": "en",
    "target_language": "es",
    "duration_seconds": 342,
    "output_url": "https://cdn.nur.ai/dubbing/dub_789xyz/output.mp4",
    "status": "completed"
  },
  "timestamp": "2026-01-15T14:30:00.000Z",
  "webhook_id": "wh_abc123"
}

Payload Fields

The id is a unique identifier for the delivery event. The data object contains event-specific fields that vary by event type. Use the webhook_id to correlate deliveries with your registered webhook.

Signature Verification

When you provide a signing secret during webhook creation, Nur includes a X-Nur-Signature header with each delivery. This header contains an HMAC-SHA256 signature of the raw request body, allowing you to verify the webhook was sent by Nur and has not been tampered with.

import hmac
import hashlib
def verify_webhook(payload_body, signature_header, secret):
    """Verify that a webhook payload was sent by Nur."""
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256,
    ).hexdigest()
    signature = signature_header.replace("sha256=", "")
    if not hmac.compare_digest(expected, signature):
        raise ValueError("Invalid webhook signature")
    return True
# Usage in a Flask route
from flask import request
@app.route("/webhooks/nur", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Nur-Signature")
    verify_webhook(request.data, signature, "whsec_your_secret")
    event = request.json
    print(f"Received event: {event['event']}")
    return "", 200

Retry Policy

If your endpoint does not return a 2xx status code within 30 seconds, Nur will retry the delivery using exponential backoff. A maximum of 5 retry attempts will be made before the delivery is marked as failed.

Attempt	Delay	Cumulative Time
1st retry	1 minute	1 minute
2nd retry	5 minutes	6 minutes
3rd retry	30 minutes	36 minutes
4th retry	2 hours	2 hours 36 minutes
5th retry	24 hours	26 hours 36 minutes

Important

Your endpoint must respond with a 2xx HTTP status code within 30 seconds. Any other response code or a timeout will be treated as a failure and trigger a retry. Ensure your endpoint processes webhooks asynchronously if the handling logic takes longer than a few seconds.

Managing Webhooks

Use the following endpoints to list and delete your registered webhooks.

# GET /v1/webhooks - List all registered webhooks
curl https://api.nur.ai/v1/webhooks \
  -H "Authorization: Bearer nur_your_api_key"
# Response
{
  "webhooks": [
    {
      "id": "wh_abc123",
      "url": "https://your-app.com/webhooks/nur",
      "events": ["dubbing.completed", "voice.clone.completed"],
      "created_at": "2026-01-10T08:00:00.000Z",
      "status": "active"
    }
  ]
}