Webhooks

Receba no seu servidor, em tempo real, os eventos da sua operação na Pitra.

Como funciona

Crie uma API Key com o scope webhooks:manage.
Crie um endpoint https público na Pitra.
Escolha os eventos que quer receber.
Receba a requisição POST no seu servidor.
Valide o header Pitra-Signature usando o corpo bruto.
Responda 2xx rapidamente.
Deduplique pelo id do evento.
Processe o evento de forma assíncrona.

Detalhes de assinatura em Assinatura e de retentativas em Retries.

O objeto endpoint

{
  "object": "webhook_endpoint",
  "id": "3f2e1d0c-9b8a-4756-8493-2a1b0c9d8e7f",
  "url": "https://minhaloja.com/webhooks/pitra",
  "description": "Integração ERP",
  "status": "active",
  "events": ["sale.approved", "sale.refunded"],
  "secret": "whsec_...",
  "created_at": "2026-07-30T12:00:00.000Z",
  "updated_at": "2026-07-30T12:00:00.000Z"
}

O campo secret é retornado apenas na criação e não pode ser recuperado depois.

Criar endpoint

POST/api/public/v1/webhooksscope webhooks:manage

Campo	Tipo	Obrigatório	Regras
`url`	string	Sim	https público, portas 443 ou 8443.
`events`	string[]	Sim	Ao menos um evento do catálogo.
`description`	string \| null	Não	Rótulo interno.
`status`	string	Não	active (padrão) ou paused.

URLs com IP privado, loopback, localhost, domínio interno, credenciais embutidas ou porta fora de 443/8443 são recusadas com 400 invalid_request. Limite de 10 endpoints por loja. Aceita Idempotency-Key.

curl -X POST https://pitra.com.br/api/public/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://minhaloja.com/webhooks/pitra",
    "description": "Integração ERP",
    "events": ["sale.approved", "sale.refunded"]
  }'

Resposta 201: o endpoint, incluindo secret.

Listar endpoints

GET/api/public/v1/webhooksscope webhooks:read

Query: limit (1–100, padrão 20) e starting_after. O secret nunca aparece na listagem.

curl "https://pitra.com.br/api/public/v1/webhooks?limit=20" \
  -H "Authorization: Bearer sk_live_..."

Consultar endpoint

GET/api/public/v1/webhooks/{id}scope webhooks:read

curl https://pitra.com.br/api/public/v1/webhooks/3f2e1d0c-9b8a-4756-8493-2a1b0c9d8e7f \
  -H "Authorization: Bearer sk_live_..."

Atualizar endpoint

PATCH/api/public/v1/webhooks/{id}scope webhooks:manage

Campos opcionais: url, description, events e status (active, paused ou disabled). Endpoints pausados não recebem entregas.

curl -X PATCH https://pitra.com.br/api/public/v1/webhooks/3f2e1d0c-9b8a-4756-8493-2a1b0c9d8e7f \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

Remover endpoint

DELETE/api/public/v1/webhooks/{id}scope webhooks:manage

Remove o endpoint. O histórico de entregas é preservado.

curl -X DELETE https://pitra.com.br/api/public/v1/webhooks/3f2e1d0c-9b8a-4756-8493-2a1b0c9d8e7f \
  -H "Authorization: Bearer sk_live_..."

Testar webhook

POST/api/public/v1/webhooks/{id}/testscope webhooks:manage

Enfileira um evento de teste assinado para o endpoint. Resposta 202.

curl -X POST https://pitra.com.br/api/public/v1/webhooks/3f2e1d0c-9b8a-4756-8493-2a1b0c9d8e7f/test \
  -H "Authorization: Bearer sk_live_..."

Histórico de entregas

GET/api/public/v1/webhooks/{id}/deliveriesscope webhooks:read

Últimas 20 tentativas do endpoint.

{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": "...",
      "event_id": "...",
      "event_type": "sale.approved",
      "attempt": 1,
      "response_status": 200,
      "delivered_at": "2026-07-30T12:00:03.000Z",
      "failed_at": null,
      "next_retry_at": null,
      "created_at": "2026-07-30T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}