Webhooks
Com uma URL de webhook configurada, seu servidor é notificado quando um trabalho de tradução de arquivo (/jobs) termina (com sucesso ou não). Trabalhos cancelados com POST /jobs/{id}/cancel não enviam nenhum callback. Para operações de documentos e trabalhos de mídia, consulte seus próprios endpoints de consulta.
Gerenciar webhooks
Seção intitulada “Gerenciar webhooks”Gerenciados por meio da API, até 3 por usuário:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} deleteCrie um exemplo:
curl -X POST https://omnidoc.top/api/v1/webhooks \ -H "X-API-Key: sk_your_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/hooks/omnidoc", "secret": "your-signing-secret", "events": ["job.completed"], "description": "Production callback" }'A URL deve ser acessível pela internet pública, preferencialmente via HTTPS; redes privadas, endereços locais e URLs malformados retornam 400. O método PATCH pode alterar url, secret, events, description e status (active / disabled).
Formato de retorno de chamada
Seção intitulada “Formato de retorno de chamada”POST your-webhook-urlContent-Type: application/jsonX-Webhook-Event: job.completedX-Webhook-Timestamp: 1782900150X-Webhook-Signature: sha256=...{ "event": "job.completed", "timestamp": 1782900150, "data": { "job_id": "q3f8s6c2a9m1k4tx", "status": "completed", "file_name": "report.docx", "char_count": 12840 }}Eventos
Seção intitulada “Eventos”| Evento | Quando |
|---|---|
job.completed | Um trabalho termina; data.status é completed ou failed |
Trabalhos com falha também utilizam o evento job.completed; diferencie-os por data.status == "failed" e pelo opcional data.error. Trabalhos bem-sucedidos não possuem o campo error. data.char_count é o número de caracteres na tradução, 0 para trabalhos com falha.
events aceita apenas job.completed e * (todos os eventos); outros valores ou uma lista vazia retornam 422. Em um PATCH, omita os campos que não deseja alterar; enviar null também retorna 422.
Verifique a assinatura
Seção intitulada “Verifique a assinatura”Ao definir um secret no webhook, cada callback contém X-Webhook-Signature. Verifique isso com HMAC-SHA256 no corpo da solicitação bruta raw request body :
import hashlibimport hmacimport jsonimport time
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature)
def parse_webhook(payload: bytes, signature: str, secret: str, tolerance: int = 12 * 3600) -> dict: if not verify_webhook(payload, signature, secret): raise ValueError("invalid signature") event = json.loads(payload) if abs(time.time() - event["timestamp"]) > tolerance: raise ValueError("stale event") return eventA assinatura cobre apenas o corpo, não os cabeçalhos. Para proteção contra repetição, verifique timestamp no corpo após a assinatura ser validada (é igual a X-Webhook-Timestamp, mas apenas o valor do corpo é assinado) e deduplique por meio de data.job_id e data.status. As tentativas de reenvio enviam o corpo da primeira entrega inalterado, com o mesmo timestamp, e a última tentativa ocorre cerca de 8,6 horas após a primeira entrega; portanto, não reduza essa janela para menos do que esse período (o exemplo utiliza 12 horas).
Entrega
Seção intitulada “Entrega”- O receptor deve retornar
2xxdentro de 15 segundos para que a entrega seja considerada bem-sucedida; redirecionamentos não são seguidos. - Entregas com falha (timeout, erro de conexão ou não-
2xx) são retentadas automaticamente: 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas após a falha anterior, no máximo 6 entregas por evento, depois não há mais tentativas. - As tentativas de reenvio são enviadas para o URL atual do webhook com o corpo inalterado (
timestamp,datae a assinatura correspondem à primeira entrega; se osecrettiver sido alterado nesse ínterim, o novosecreté usado para assinar); eventos já entregues não são enviados novamente - Quando um webhook é desativado, excluído ou não está mais inscrito no evento, suas tentativas de reenvio pendentes são canceladas.
- Os receptores devem tratar os eventos de forma idempotente, conforme
data.job_idedata.status, e responder rapidamente após persisti-los com segurança. - Vários webhooks de uma mesma conta são entregues em paralelo; um receptor lento não atrasa os demais.
- Após 10 entregas consecutivas falhadas (incluindo tentativas de reenvio), o webhook é desativado automaticamente; reative-o com
PATCHassim que o receptor estiver corrigido. GET /api/v1/webhooksexibe o último horário de acionamento, o código de status e as falhas consecutivas de cada webhook