---
title: "API e webhooks da Vixpi: automatize serviços, faturas e tickets - Vixpi"
description: "Como usar a API REST da Vixpi com chave vxp\\_, receber webhooks assinados com HMAC e tratar limites, erros e idempotência sem duplicar operação."
canonical: "https://vixpi.host/blog/api-webhooks-automatizar-hospedagem"
---

# API e webhooks da Vixpi: automatize serviços, faturas e tickets - Vixpi

> Como usar a API REST da Vixpi com chave vxp\_, receber webhooks assinados com HMAC e tratar limites, erros e idempotência sem duplicar operação.

# API e webhooks da Vixpi: automatize serviços, faturas e tickets

Tudo o que você faz no painel da Vixpi passa por uma API REST, e a mesma API está aberta para os seus scripts. Com ela e com os webhooks dá para levar faturas para o seu ERP, abrir ticket a partir do monitoramento ou avisar a equipe quando um serviço muda de estado. Este guia cobre o essencial para começar sem surpresa.

 Equipe Vixpi  4 min de leitura Publicado em 08/11/2026 

## Endereço e chave de API

O endereço base é https://api.vixpi.host/api/v1\. As chaves são criadas em Painel, Desenvolvedor, Chaves, começam com vxp\_ e aparecem uma única vez. Cada chave recebe só os escopos que você marcar, como tickets:read para ler tickets, e pode ter validade.

A chave vai no cabeçalho Authorization: Bearer seguido do valor. Para um app de terceiros que age em nome de outros clientes, o caminho é OAuth, e não uma chave compartilhada.

## Erros, limites e versão

Os erros chegam em JSON com os campos error, code e message. O code é estável e serve para o seu código decidir o que fazer; a message é texto para gente ler.

Cada token pode fazer 60 requisições por minuto. As respostas trazem os cabeçalhos RateLimit, e, ao passar do limite, a API responde 429 com Retry-After dizendo quanto esperar. Existe também um limite por IP.

A versão v1 só recebe mudanças que acrescentam: campo novo, rota nova. O que muda fica registrado no changelog em vixpi.host/developers/changelog.

## Idempotência: repetir sem duplicar

Rede cai, timeout acontece e o script tenta de novo. Numa operação que cria algo, como abrir um ticket, isso pode duplicar o resultado. Para evitar, mande o cabeçalho Idempotency-Key com um valor único por operação, de 1 a 255 caracteres.

A API guarda a resposta por 24 horas. Se a mesma chave chegar de novo nesse período, ela devolve a resposta original em vez de executar outra vez e marca a resposta com o cabeçalho Idempotent-Replayed.

## Referência OpenAPI

A especificação completa está em OpenAPI 3.1, em /api/v1/openapi.json. A referência navegável fica em vixpi.host/developers/referencia, com cada rota, parâmetro e resposta, e dá para testar chamadas ali mesmo usando a sua chave.

Com o arquivo OpenAPI dá para gerar um cliente tipado na linguagem que você usa, em vez de escrever cada chamada à mão.

## Webhooks: a Vixpi avisa você

Webhook inverte a direção: em vez de o seu sistema perguntar de tempos em tempos, a Vixpi faz um POST no seu endereço quando algo acontece. A configuração fica em Painel, Desenvolvedor, Webhooks. O endereço precisa ser https, na porta 443 ou 8443.

Você assina eventos exatos ou uma família inteira, como invoice.\* para todas as mudanças de fatura. Há eventos de serviços, de faturas e de tickets, e o botão Enviar teste manda um evento webhook.test para conferir a integração.

- X-Vixpi-Event: o tipo do evento.
- X-Vixpi-Delivery: o identificador da entrega.
- X-Vixpi-Signature: a assinatura HMAC-SHA256, no formato t=<timestamp>,v1=<assinatura>.

## Conferir a assinatura

Cada endpoint tem um segredo que começa com whsec\_ e aparece uma única vez. Com ele, o seu servidor calcula o HMAC-SHA256 da mensagem e compara com o valor de v1\. Assinatura diferente significa que a requisição não veio da Vixpi ou foi alterada no caminho, e deve ser recusada.

Recuse também mensagens com timestamp mais antigo que 5 minutos. Isso impede que alguém capture uma entrega legítima e a reenvie depois.

## Responder rápido e aguentar repetição

Responda com um status 2xx em até 10 segundos. Se o processamento for demorado, grave o evento numa fila, responda e processe depois. Redirecionamentos não são seguidos, então o endereço cadastrado precisa ser o final.

Se a entrega falhar, a Vixpi faz até 7 tentativas: a primeira na hora, a segunda 1 minuto depois da falha e as seguintes 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas depois. Por isso o mesmo evento pode chegar mais de uma vez. Guarde o id de cada evento processado e ignore os repetidos.

Quando a última tentativa falha, a entrega fica como esgotada no histórico do endpoint, no painel. Depois de 20 entregas esgotadas seguidas, sem nenhum sucesso no meio, o endpoint é desativado. Corrija o servidor e reative pelo painel.

## Exemplos de integração

Alguns usos que resolvem trabalho manual de quem opera serviços na Vixpi. Todos combinam um evento com uma rota da API, para buscar os detalhes que o evento não traz.

- invoice.paid: libera o acesso no seu sistema ou lança o pagamento no financeiro assim que a fatura é paga.
- invoice.created: busca a fatura nova pela API e registra no seu ERP antes do vencimento.
- service.suspended e service.unsuspended: avisam a equipe num canal interno quando um serviço é suspenso e quando volta.
- ticket.replied: leva a resposta do suporte para a ferramenta de chamados que a sua equipe já usa.

Coloque em prática na Vixpi

Autenticação, referência OpenAPI, webhooks e MCP.

[Abrir a documentação da API ](https://vixpi.host/developers)

## Continue lendo

- [ Tutoriais MCP: conecte Claude, ChatGPT e Cursor à sua conta Vixpi  4 min](https://vixpi.host/blog/mcp-conectar-claude-chatgpt-hospedagem)
- [ Tutoriais Como apontar domínio para uma hospedagem  5 min](https://vixpi.host/blog/apontar-dominio-para-hospedagem)
- [ Tutoriais Como configurar o Cloudflare no seu domínio  4 min](https://vixpi.host/blog/configurar-cloudflare)
