> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Ricevi un callback HTTP nel momento in cui un progetto raggiunge una pietra miliare, invece di eseguire il polling

# Webhook

I webhook consentono a VoiceCheap di notificare il tuo server non appena accade qualcosa, così puoi interrompere il polling
`GET /v1/translate/{projectId}/status`.

> [!NOTE]
>
> Ogni consegna viene tentata una sola volta. Non sono previsti nuovi tentativi; continua a interrogare lo stato per gli eventi importanti.

## Configurazione

1. Apri la [pagina API](https://app.voicecheap.ai/page-api) nel tuo account VoiceCheap.
2. In **Webhook**, seleziona **Genera chiave di firma**. La chiave che inizia con `whsec_` appare una sola volta: copiala e conservala sul tuo server.
3. Inserisci un URL `https` in **URL di destinazione** e seleziona **Salva**.

Tutto qui. Ogni progetto che avvii da quel momento in poi invierà eventi a quell'endpoint.

> [!NOTE]
>
> Gli URL dei webhook devono usare HTTPS sulla porta 443 e risolversi in un indirizzo di rete pubblico. Gli URL con credenziali o frammenti, gli
> indirizzi privati o riservati e i reindirizzamenti vengono rifiutati. Questo vale per l’endpoint dell’account e per gli URL specifici dei singoli
> progetti.

Usa `webhooks_get`, `webhooks_update` e `webhooks_delete` tramite l’API delle azioni o MCP. Usa `webhooks_create_secret` solo tramite l’API delle azioni REST. Conserva in modo sicuro il segreto di firma quando viene restituito; MCP non permette di eseguire questa azione né di consultarne il risultato.

### Sovrascrittura dell'endpoint per richiesta

`POST /v1/translate` e `POST /v1/projects` accettano un campo opzionale `webhookUrl` che sovrascrive
l'endpoint dell'account solo per quel progetto. È utile per inviare il traffico di staging altrove:

Puoi impostare `webhookUrl` anche su `POST /v1/projects/{projectId}/dub` per aggiornare la destinazione di un progetto esistente.

```bash theme={null}
curl -X POST "https://api.voicecheap.ai/v1/projects" \
  -H "x-api-key: vc_your-key" \
  -F "file=@interview.mp4" \
  -F "targetLanguage=german" \
  -F "webhookUrl=https://staging.your-server.com/voicecheap/webhooks"
```

Il segreto di firma è sempre il segreto dell'account; cambia solo la destinazione.

## Eventi

| Evento | Si attiva quando |
| - | - |
| `project.created` | Il progetto esiste e la sua trascrizione è archiviata. Questo è il tuo segnale per scaricare l'SRT. |
| `project.creation.failed` | Il progetto non ha potuto essere creato. |
| `project.translation.completed` | La traduzione è terminata e gli output sono pronti. |
| `project.translation.failed` | La traduzione non è riuscita. |
| `project.lipsync.completed` | Sincronizzazione labiale completata. |
| `project.lipsync.failed` | Sincronizzazione labiale non riuscita. |

> [!NOTE]
>
> Non esiste un evento separato per la trascrizione. La creazione del progetto risponde prima che la trascrizione sia completata. `project.created`
> viene inviato solo dopo che la trascrizione è stata salvata; puoi quindi recuperarla con [`POST /v1/projects/{projectId}/transcript`](https://api-docs.voicecheap.ai/docs/it/api-reference/project-transcript).

## Payload

Ogni consegna è un `POST` con un corpo JSON:

```json theme={null}
{
  "type": "project.created",
  "eventId": "evt_9f2c4b1d8e7a4c3f9b2d1e0a5c6b7d8e",
  "projectId": "7fa7d3a3-4f2b-4c1e-9a6d-2b3c4d5e6f70",
  "workflow": "transcription",
  "status": "success",
  "targetLanguage": "german",
  "error": null,
  "occurredAt": "2026-08-19T09:12:00.000Z"
}
```

| Campo | Tipo | Descrizione |
| - | - | - |
| `type` | string | Uno degli eventi sopra indicati. |
| `eventId` | string | Univoco per evento. Usalo per la deduplicazione. |
| `projectId` | string | Il progetto a cui appartiene questo evento. |
| `workflow` | string | `transcription` o `translation`. |
| `status` | string | `success` o `failed`. |
| `targetLanguage` | string | Presente solo negli eventi specifici della lingua. |
| `error` | object \| null | Negli eventi `*.failed`, la stessa forma `{ code, message }` dell'API REST. Vedi [Codici di errore](https://api-docs.voicecheap.ai/docs/it/api-reference/errors.md). |
| `occurredAt` | string | Timestamp ISO 8601. |

Il payload è intenzionalmente leggero. Chiama l'API REST per il contenuto stesso.

## Verifica della firma

Ogni consegna trasporta queste intestazioni:

| Intestazione | Descrizione |
| - | - |
| `X-VoiceCheap-Signature` | `sha256=<hex>` — HMAC-SHA256 del payload, codificato dal tuo segreto di firma. |
| `X-VoiceCheap-Timestamp` | Secondi Unix, inclusi nella stringa firmata in modo da poter rifiutare le repliche. |
| `X-VoiceCheap-Event-Id` | Stesso valore di `eventId` nel corpo, utile nelle richieste di supporto. |

La firma copre `<timestamp>.<raw body>`, quindi è diversa a ogni consegna e dimostra sia
che la richiesta proviene da VoiceCheap sia che il corpo non è stato modificato durante il transito.

```js theme={null}
import crypto from 'crypto';
import express from 'express';

const app = express();

// The raw body is required: parsing and re-serializing changes the bytes and the signature will
// never match. This is the single most common cause of failed verification.
app.post('/voicecheap/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const timestamp = req.header('X-VoiceCheap-Timestamp');
  const signature = req.header('X-VoiceCheap-Signature')?.replace('sha256=', '') ?? '';

  // Reject anything older than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const expected = crypto.createHmac('sha256', process.env.VOICECHEAP_WEBHOOK_SECRET).update(`${timestamp}.${rawBody}`).digest('hex');

  const isValid = expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

  if (!isValid) return res.status(401).send('Invalid signature');

  const event = JSON.parse(rawBody);
  // Acknowledge quickly, then process asynchronously.
  res.status(200).send('ok');
  handleEvent(event);
});
```

> [!WARNING]
>
> Verifica la firma prima di considerare attendibile una consegna. Il tuo endpoint è un URL pubblico e la firma è ciò che distingue un vero evento
> VoiceCheap da qualsiasi altra cosa che lo raggiunga.

## Risposta

Rispondi con qualsiasi stato `2xx` per confermare la ricezione. Rispondi entro **10 secondi** — conferma prima e svolgi
il lavoro in seguito, invece di elaborare prima di rispondere.

Una risposta non 2xx o un timeout viene registrato come consegna non riuscita e, per ora, non viene riprovato.

## Rotazione del segreto

Seleziona **Ruota** nella pagina API per generare un nuovo segreto. Il precedente smette di funzionare
immediatamente, quindi distribuisci il nuovo segreto sul tuo server non appena lo ruoti.

L'eliminazione del webhook rimuove sia l'endpoint che il segreto e le consegne si interrompono.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.