> ## 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.

# Webhooks

> Receba um retorno de chamada HTTP no momento em que um projeto atinge um marco, em vez de sondar

# Webhooks

Webhooks permitem que VoiceCheap notifique seu servidor assim que algo acontece, para que você possa parar de sondar
`GET /v1/translate/{projectId}/status`.

> [!NOTE]
>
> Cada entrega é tentada uma única vez. Não há novas tentativas; continue consultando o status para eventos que você não pode perder.

## Configuração

1. Abra a [página da API](https://app.voicecheap.ai/page-api) em sua conta VoiceCheap.
2. Em **Webhooks**, selecione **Gerar chave de assinatura**. A chave que começa por `whsec_` aparece apenas uma vez; copie-a e guarde-a no servidor.
3. Introduza um URL `https` em **URL de destino** e selecione **Guardar**.

Isso é tudo. Cada projeto que você iniciar a partir de então entregará eventos para esse endpoint.

> [!NOTE]
>
> As URLs de webhook devem usar HTTPS na porta 443 e resolver para um endereço de rede público. URLs com credenciais ou fragmentos, endereços privados
> ou reservados e redirecionamentos são recusados. Isso se aplica ao endpoint da conta e às URLs específicas de cada projeto.

Use `webhooks_get`, `webhooks_update` e `webhooks_delete` pela API de ações ou pelo MCP. Use `webhooks_create_secret` apenas pela API de ações REST. Armazene o segredo de assinatura com segurança quando ele for retornado; o MCP não permite executar essa ação nem consultar seu resultado.

### Substituindo o endpoint por solicitação

`POST /v1/translate` e `POST /v1/projects` aceitam um campo opcional `webhookUrl` que substitui o
endpoint da conta apenas para aquele projeto. É útil para enviar tráfego de teste para outro lugar:

Você também pode definir `webhookUrl` em `POST /v1/projects/{projectId}/dub` para atualizar o destino de um projeto existente.

```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"
```

O segredo de assinatura é sempre o segredo da conta; apenas o destino muda.

## Eventos

| Evento | Dispara quando |
| - | - |
| `project.created` | O projeto existe e sua transcrição está armazenada. Este é o seu sinal para baixar o SRT. |
| `project.creation.failed` | O projeto não pôde ser criado. |
| `project.translation.completed` | A tradução terminou e as saídas estão prontas. |
| `project.translation.failed` | A tradução falhou. |
| `project.lipsync.completed` | Sincronização labial concluída. |
| `project.lipsync.failed` | A sincronização labial falhou. |

> [!NOTE]
>
> Não há um evento separado de transcrição. A criação do projeto responde antes de a transcrição terminar. `project.created` é enviado somente após a
> transcrição ser armazenada; então você pode obtê-la com [`POST /v1/projects/{projectId}/transcript`](https://api-docs.voicecheap.ai/docs/pt/api-reference/project-transcript).

## Payload

Cada entrega é um `POST` com um 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 | Descrição |
| - | - | - |
| `type` | string | Um dos eventos acima. |
| `eventId` | string | Único por evento. Use-o para desduplicar. |
| `projectId` | string | O projeto ao qual este evento pertence. |
| `workflow` | string | `transcription` ou `translation`. |
| `status` | string | `success` ou `failed`. |
| `targetLanguage` | string | Presente apenas em eventos específicos de idioma. |
| `error` | object \| null | Em eventos `*.failed`, o mesmo formato `{ code, message }` da API REST. Veja [Códigos de Erro](https://api-docs.voicecheap.ai/docs/pt/api-reference/errors.md). |
| `occurredAt` | string | Timestamp ISO 8601. |

O payload é intencionalmente leve. Chame a API REST para obter o conteúdo em si.

## Verificando a assinatura

Cada entrega carrega estes cabeçalhos:

| Cabeçalho | Descrição |
| - | - |
| `X-VoiceCheap-Signature` | `sha256=<hex>` — HMAC-SHA256 do payload, codificado pelo seu segredo de assinatura. |
| `X-VoiceCheap-Timestamp` | Segundos Unix, incluídos na string assinada para que você possa rejeitar replays. |
| `X-VoiceCheap-Event-Id` | Mesmo valor que `eventId` no corpo, útil em solicitações de suporte. |

A assinatura cobre `<timestamp>.<raw body>`, portanto, é diferente em cada entrega e prova tanto
que a solicitação veio do VoiceCheap quanto que o corpo não foi modificado em trânsito.

```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]
>
> Verifique a assinatura antes de confiar em uma entrega. Seu endpoint é uma URL pública, e a assinatura é o que distingue um evento real VoiceCheap
> de qualquer outra coisa que chegue até ele.

## Respondendo

Responda com qualquer status `2xx` para confirmar o recebimento. Responda dentro de **10 segundos** — confirme primeiro e faça
o trabalho depois, em vez de processar antes de responder.

Uma resposta que não seja 2xx ou um tempo limite é registrada como uma entrega falha e, por enquanto, não é tentada novamente.

## Rotacionando o segredo

Selecione **Rotacionar** na página da API para gerar um novo segredo. O anterior para de funcionar
imediatamente, portanto, implemente o novo segredo em seu servidor assim que rotacionar.

Excluir o webhook remove tanto o endpoint quanto o segredo, e as entregas param.


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