Webhooks & Eventos

Eventos em tempo real. Entregues com assinatura HMAC.

O PaperOffice chama seu endpoint assim que um documento, trabalho, workspace ou tarefa é alterado. Sem polling.

22 tipos de eventos, assinatura HMAC-SHA256, três estratégias de retry e um registro de entrega por tentativa.

Inscrever-se no primeiro webhook Iniciar a primeira chamada de API

HMAC-SHA256 em cada entrega Até 10 repetições (padrão 5) Idempotente por ID do evento

Eventos em tempo real. Entregues com assinatura HMAC.

Infraestrutura própria da UE Seus dados permanecem na Europa.
ISO/IEC 27001 certificado Segurança certificada.
Mais de 24 anos de experiência Comprovado. Estável. Preparado para o futuro.

Eventos disponíveis

22 tipos de eventos, agrupados por entidade

Inscreva-se em eventos individuais ou use o curinga * para todos.

Documentos

document.uploaded Novo documento carregado em um workspace
document.created Alias para document.uploaded (compatibilidade)
document.processed Pipeline OCR/AI-IDP concluída com sucesso
document.edited Documento editado: metadados, tags ou conteúdo atualizados
document.deleted Documento excluído; delete_mode mostra trash (Lixeira em Business e Compliance) ou instant (definitivamente no padrão)
document.restored Documento restaurado da lixeira (Business e Compliance)
document.moved Documento movido entre workspaces
document.version_created Nova versão de um documento existente
document.lifecycle_changed Status de retenção/arquivamento alterado
document.comment_added Comentário em um documento criado
document.note_added Nota interna anexada
document.tag_added Tag atribuída a um documento
document.legal_hold_placed Legal Hold ativado (imutável)
document.legal_hold_released Legal Hold revogado

Trabalhos

job.completed Trabalho assíncrono concluído com sucesso
job.failed Trabalho assíncrono falhou definitivamente
job.progress Atualização de progresso em trabalhos longos

Workspaces

workspace.shared Workspace compartilhado com um usuário ou equipe
workspace.unshared Acesso ao Workspace revogado

Tarefas

task.created Nova tarefa criada
task.completed Tarefa marcada como concluída
task.overdue Tarefa ultrapassou a data de vencimento

Payload e cabeçalho

Cada entrega segue o mesmo esquema

Corpo JSON previsível, cabeçalhos HTTP fixos, carimbo de data/hora UTC ISO-8601.

Corpo da Solicitação

{
  "event_type": "document.processed",
  "event_id": "a3b7f9c1d4e8b2a6c9f1d4e7b2a5c8f1",
  "timestamp": "2026-04-17T14:23:11Z",
  "subscription_id": 42,
  "data": {
    "pofid": "doc_01HZY8K3M7P2Q9R5T1V6W4X2Y8",
    "workspace_id": 17,
    "filename": "invoice-2026-04-17.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 284521,
    "processing_result": {
      "ocr_done": true,
      "classification": "invoice",
      "confidence": 0.98
    }
  }
}

Cabeçalhos da Solicitação HTTP

Cabeçalho Valor de Exemplo Significado

Content-Type application/json Sempre JSON, codificado em UTF-8

User-Agent PaperOffice-Webhook/1.0 Identificador fixo para listas de permissão do firewall

X-PaperOffice-Event document.processed Tipo de evento entregue

X-PaperOffice-Event-ID a3b7f9c1… ID exclusivo de 128 bits. Use-o como chave de idempotência.

X-PaperOffice-Subscription-ID 42 ID da assinatura que recebe o evento

X-PaperOffice-Signature sha256=… HMAC-SHA256 do corpo bruto, codificado em hexadecimal

cURL

1curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \2  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "My Production Webhook",6    "url": "https://yourdomain.com/webhooks/paperoffice",7    "events": ["document.processed", "job.completed", "job.failed"],8    "retry_policy": "exponential",9    "max_retries": 5,10    "timeout_ms": 1000011  }'

1import crypto from 'crypto';2import express from 'express';34const app = express();5const WEBHOOK_SECRET = process.env.PAPEROFFICE_WEBHOOK_SECRET;67app.post('/webhooks/paperoffice', express.raw({ type: 'application/json' }), (req, res) => {8  const signature = req.header('X-PaperOffice-Signature'); // "sha256=..."9  const eventId   = req.header('X-PaperOffice-Event-ID');10  const eventType = req.header('X-PaperOffice-Event');1112  const expected = 'sha256=' + crypto13    .createHmac('sha256', WEBHOOK_SECRET)14    .update(req.body)15    .digest('hex');1617  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {18    return res.status(401).send('invalid signature');19  }2021  const event = JSON.parse(req.body.toString());22  // store eventId as idempotency key -> never process the same ID twice23  console.log(eventType, event.data);24  res.status(200).send('ok');25});

1import hmac, hashlib, os2from flask import Flask, request, abort34app = Flask(__name__)5WEBHOOK_SECRET = os.environ["PAPEROFFICE_WEBHOOK_SECRET"]67@app.route("/webhooks/paperoffice", methods=["POST"])8def paperoffice_webhook():9    signature  = request.headers.get("X-PaperOffice-Signature", "")10    event_id   = request.headers.get("X-PaperOffice-Event-ID", "")11    event_type = request.headers.get("X-PaperOffice-Event", "")1213    expected = "sha256=" + hmac.new(14        WEBHOOK_SECRET.encode(),15        request.get_data(),16        hashlib.sha256,17    ).hexdigest()1819    if not hmac.compare_digest(signature, expected):20        abort(401)2122    payload = request.get_json()23    # store event_id as idempotency key in your DB24    print(event_type, payload["data"])25    return "ok", 200

1<?php2// PaperOffice webhook receiver with HMAC-SHA256 signature verification3$secret = getenv('PAPEROFFICE_WEBHOOK_SECRET');4$raw    = file_get_contents('php://input');56$signature  = $_SERVER['HTTP_X_PAPEROFFICE_SIGNATURE'] ?? '';7$event_id   = $_SERVER['HTTP_X_PAPEROFFICE_EVENT_ID'] ?? '';8$event_type = $_SERVER['HTTP_X_PAPEROFFICE_EVENT'] ?? '';910$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);11if (!hash_equals($expected, $signature)) {12    http_response_code(401);13    exit('invalid signature');14}1516$event = json_decode($raw, true);17// store event_id as idempotency key in your DB18error_log("{$event_type}: " . json_encode($event['data']));19http_response_code(200);20echo 'ok';

Verificação de assinatura

Verifique cada entrega com HMAC-SHA256

Calcule o HMAC-SHA256 sobre o corpo bruto da solicitação usando seu segredo compartilhado e compare o resultado com X-PaperOffice-Signature — obrigatório com tempo constante.

Comparação em tempo constante
hash_equals, hmac.compare_digest ou crypto.timingSafeEqual: A comparação não deve revelar diferenças de tempo.
Assinar o corpo bruto
A assinatura é válida para o corpo da solicitação inalterado. Analise o JSON apenas após a verificação, caso contrário, o hash será diferente.
Inscrever-se via API
POST /latest/webhooks/subscribe com name, url e events. Se secret permanecer vazio, o PaperOffice o gera e o retorna uma única vez.

Autenticação e Chaves Coleção Postman

Retentativa e Entrega

Três estratégias de retentativa, até 10 repetições

Escolha a política por assinatura. Cada tentativa é registrada com código de status, corpo da resposta e medição de tempo.

Padrão exponential
Exponencial (Padrão)

O intervalo entre as tentativas dobra após cada falha.
linear
Linear

O intervalo entre as tentativas aumenta em um passo fixo.
none
Nenhuma

Sem repetição, mesmo em caso de erros 5xx (enviar e esquecer). Útil para hooks de teste.

Sucesso HTTP 2xx dentro da janela de tempo limite
Máx. repetições Até 10 repetições (padrão: 5)
Tempo limite 1.000–30.000 ms por tentativa (padrão 10.000). A primeira tentativa de entrega é limitada a 2 ou 5 segundos, dependendo do evento; as repetições utilizam o valor completo.
Log de entrega Cada tentativa é registrada; o log permanece mesmo após a exclusão da assinatura.

Gestão-API

Cinco endpoints em /latest/webhooks/

Criar, listar, atualizar e excluir assinaturas — além de um endpoint de teste. Cada chamada requer um token Bearer.

POST /webhooks/subscribe Criar assinatura; as cargas úteis são assinadas com HMAC-SHA256 Ferramenta MCPpo-webhooks-subscribe
GET /webhooks/list Listar todas as assinaturas de webhook da conta Ferramenta MCPpo-webhooks-list
POST /webhooks/update Atualizar URL, eventos, cabeçalhos, política de retry ou status ativo Ferramenta MCPpo-webhooks-update
POST /webhooks/delete Cancelar assinatura; o registro de entrega permanece válido Ferramenta MCPpo-webhooks-delete
POST /webhooks/test Enviar evento de teste para uma assinatura e verificar a entrega Ferramenta MCPpo-webhooks-test

Ver servidor MCP Coleção Postman

Segurança

Fortalecido desde a base

Seis mecanismos que entram em ação em cada entrega — do lado da PaperOffice e do seu.

HMAC-SHA256
Cada entrega é assinada com o seu segredo. A comparação deve ocorrer obrigatoriamente em tempo constante.
Proteção SSRF
IPs privados e internos, localhost e endpoints de metadados da nuvem são bloqueados durante a assinatura e o envio.
Seguro contra DNS Rebinding
O endereço de destino é verificado novamente no momento da entrega.
HTTPS recomendado
http e https são aceitos. Para produção, recomendamos HTTPS.
Idempotência por Event-ID
Cada entrega inclui um X-PaperOffice-Event-ID exclusivo. Realize a deduplicação no seu lado.
Registro completo de entrega
Todas as tentativas são registradas: código de status, corpo da resposta, medição de tempo e mensagem de erro.

Limites

Comportamento de entrega configurável por assinatura

Defina todos os valores ao criar ou posteriormente via /webhooks/update — por assinatura, não por conta.

0–10 Repetições por entrega (padrão 5)
1.000–30.000 ms Tempo limite por tentativa (padrão 10.000, primeira tentativa 2–5 s)
3 Políticas de retry: none, linear, exponential
HMAC-SHA256 Assinatura em cada entrega

Webhooks estão disponíveis a partir do plano Professional. A visão geral de preços mostra qual plano se adapta à sua configuração.

Ver precos Autenticação e chaves

Perguntas

Perguntas frequentes sobre webhooks

Como verifico uma entrega?

Calcule HMAC-SHA256 sobre o corpo bruto da solicitação usando o segredo da sua assinatura e compare o resultado em tempo constante com o cabeçalho X-PaperOffice-Signature (formato sha256=<hex>). Se a assinatura não corresponder, responda com HTTP 401 e não processe o corpo.

De onde vem o segredo?

Ao criar a assinatura via POST /latest/webhooks/subscribe. Deixe o campo secret vazio; o PaperOffice gera um segredo e o retorna uma única vez na resposta. Você pode substituí-lo a qualquer momento via POST /latest/webhooks/update.

O que acontece se meu endpoint não responder?

Qualquer resposta fora do HTTP 2xx ou um tempo limite contam como falha. Dependendo da política de retry (exponencial, linear, nenhuma), o PaperOffice repete a entrega até o número configurado de repetições (0–10, padrão 5). Cada tentativa é registrada no log de entrega com código de status, resposta e medição de tempo.

A mesma entrega pode chegar duas vezes?

Sim, isso é possível em caso de repetições após um tempo limite. Portanto, realize a deduplicação via X-PaperOffice-Event-ID: o ID é único por evento e serve como chave de idempotência em seu banco de dados.

Quais eventos posso assinar?

22 tipos de eventos de quatro grupos: Documentos, Jobs, Workspaces e Tarefas. Você pode assinar eventos individuais ou todos com o curinga *. Além disso, você pode restringir uma assinatura usando filtros (como workspace_id ou pofid).

Em qual plano os webhooks estão incluídos?

Os webhooks estão disponíveis a partir do plano Professional. A visão geral de preços mostra qual plano se adequa à sua configuração.

Como as tabelas chegam no webhook?

Para campos de tabela (por exemplo, valores de inspeção ou itens de linha), document.processed também carrega data.extracted_tables. Sua lista tables contém uma entrada por campo de tabela com key, label, columns e rows; cada célula possui value (um número se PaperOffice tiver lido um número, caso contrário, o texto conforme impresso) e value_raw (o texto conforme impresso, ou null se não for conhecido). extracted_fields permanece inalterado. Cada entrega contém no máximo 50 tabelas com até 1.000 linhas e 40 colunas cada, 2.000 caracteres por célula e 512 KB para todas as tabelas em conjunto; se algo for truncado, truncated será true e row_count indicará o número total de linhas. A assinatura abrange todo o corpo da solicitação, incluindo extracted_tables.

O que há de novo no evento document.processed?

Novo: key_fields agora também carrega document_number (por exemplo, o número da fatura) e publisher (o emissor do documento), caso PaperOffice os tenha lido. Os itens de linha chegam como uma tabela em data.extracted_tables: a tabela com key __document__content__extraction__line_items (para campos de agente: _line_items) possui uma linha por item de linha.

Operações e confiança

O que as equipes empresariais verificam antes da primeira chamada

Contratos, segurança, suporte e limites, todos vinculados em um só lugar.

Próxima parada

Como prosseguir

O próximo passo recomendado no funil do desenvolvedor e dois desvios adequados.

Postman CollectionImportar, testar e depurar no Postman Publishable KeysChaves seguras no navegador para artefatos de IA e aplicativos frontend Primeiro chamamento de APIObter chave, enviar solicitação, verificar resposta

Voltar à entrada do desenvolvedor

Eventos em tempo real. Entregues com assinatura HMAC.

22 tipos de eventos, agrupados por entidade

Cada entrega segue o mesmo esquema

Verifique cada entrega com HMAC-SHA256

Três estratégias de retentativa, até 10 repetições

Exponencial (Padrão)

Linear

Nenhuma

Cinco endpoints em /latest/webhooks/

Fortalecido desde a base

Comportamento de entrega configurável por assinatura

Perguntas frequentes sobre webhooks

O que as equipes empresariais verificam antes da primeira chamada

Como prosseguir

DMS on-premise para a sua infraestrutura.

IA industrial pronta no Claude e ChatGPT

Nunca construa sozinho.

Document Layer em vez de infraestrutura.

Para parceiros que constroem sobre a plataforma.

Hardware próprio. Datacenter próprio.

31 ferramentas gratuitas

PaperOffice PDF Reader