Webhooks

Webhooks são os avisos que a Rotta Pay manda ao seu sistema quando algo acontece na sua conta, como um pagamento confirmado. Esta tela mostra os endpoints que recebem esses avisos e cada entrega feita a eles, com a resposta do seu servidor e o reenvio. No menu, abra Integrações → Webhooks.

A tela tem duas abas: Endpoints e Entregas. O formato de cada aviso, a lista de eventos e como conferir a assinatura estão em Webhooks, na documentação de integração.

#Quem pode mexer

Qualquer pessoa da equipe vê os endpoints e as entregas. Criar, editar, ativar, desativar, testar e excluir endpoints, rotacionar o segredo e reenviar entregas é só para quem tem o cargo Proprietário ou Administrador (veja Equipe). Para os outros cargos, a tela esconde os botões e avisa quem pode fazer.

#Criar um endpoint

1. Na aba Endpoints, clique em Novo endpoint.
2. Em URL, digite o endereço do seu sistema que vai receber os avisos. Em produção, a URL precisa começar com https://.
3. Em Eventos, marque os eventos que esse endpoint recebe. payment.completed e payment.failed já vêm marcados. Cada evento traz uma descrição curta.
4. Clique em Criar endpoint.

Alguns eventos têm um nome antigo e um nome novo, como payment.completed e charge.paid. Os dois não ficam marcados juntos: marcar um desmarca o outro.

Ao criar o endpoint, as entregas recentes que estão falhando nos seus outros endpoints, nos eventos marcados, passam a sair pelo novo e param nos antigos.

A tela recusa a URL quando:

• já existe um endpoint com a mesma URL: edite os eventos dele em vez de criar outro;
• a URL aponta para um domínio da plataforma: use o endereço do seu sistema;
• a conta chegou ao limite de endpoints ativos: desative ou remova um antes de ativar outro.

#Salve o segredo de assinatura

Depois de criar, a janela Salve seu segredo de assinatura mostra a URL e o Segredo.

1. Clique em Copiar e guarde o segredo no seu sistema.
2. Clique em Salvei.

O segredo aparece uma vez só. A janela não fecha com Esc nem com clique fora dela, só pelo Salvei ou pelo X.

Cada aviso chega assinado no cabeçalho X-RottaPay-Signature. Seu sistema usa o segredo para conferir a assinatura antes de confiar no aviso.

#Endpoints configurados

Cada endpoint mostra a URL, os eventos assinados e o selo Ativo ou Inativo. Os botões:

• Desativar e Ativar: um endpoint desativado para de receber entregas. As entregas recentes que ainda iam sair por ele passam para outro endpoint ativo que assina o mesmo evento; sem nenhum, são canceladas. Ao reativar, ele passa a receber as entregas recentes que estão falhando nos outros, como um endpoint novo.
• Testar: manda um aviso de exemplo e mostra o resultado (veja abaixo).
• Editar: troca a URL ou os eventos. Clique em Salvar. Ao trocar a URL, as entregas que estavam falhando tentam de novo na hora. Ao desmarcar um evento, as entregas pendentes dele passam para outro endpoint que o assina.
• Rotacionar: troca o segredo de assinatura.
• Excluir: o endpoint deixa de receber entregas na hora. As pendentes passam para os seus outros endpoints ativos que assinam o mesmo evento; sem nenhum, são canceladas. Não dá para desfazer. Confirme em Excluir endpoint.

#Rotacionar o segredo

O segredo atual para de valer na hora em que você confirma. Até você colocar o novo no seu servidor, ele recusa a assinatura de todo aviso, e pedidos pagos ficam sem baixa no seu sistema. Confirme em Rotacionar e revogar o atual. O novo segredo aparece na janela Novo segredo de assinatura, uma vez só.

#Testar um endpoint

O teste manda um exemplo do evento payment.completed para a URL do endpoint. A janela Resultado do teste de webhook mostra:

• Recebido (seu endpoint respondeu com um código 2xx), Timeout (não respondeu a tempo) ou Falhou;
• o código HTTP da resposta e quanto tempo ela levou;
• o erro, quando houve;
• Resposta do seu endpoint;
• o Payload enviado, que é o mesmo formato que chega em produção;
• os Headers enviados.

O teste não entra na aba Entregas. Há um limite de testes por hora: quando ele acaba, a tela avisa "Limite de testes de webhook por hora atingido. Tente de novo mais tarde."

#Entregas

A aba Entregas lista cada aviso enviado, do mais novo para o mais antigo, com quantas entregas há no total.

Filtre por estado (Todos, Entregue, Pendente, Processando, Falhou, Esgotado ou cancelado), por endpoint (Todos os endpoints) e por evento (Todos os eventos).

As colunas são Enviado em, Evento, Endpoint, Status, Código e Tentativas. Código é o código HTTP da última resposta do seu servidor, em vermelho quando é erro. Tentativas mostra as tentativas feitas e o máximo. No celular, a lista mostra só data, evento e estado; o resto fica no detalhe.

#Detalhe de uma entrega

Clique numa linha para abrir o detalhe. Ele mostra o evento, o estado, o Destino, as Tentativas, o Último HTTP, o Payload enviado, a Resposta do cliente e a lista de Tentativas, cada uma com o código HTTP, o tempo, o erro e a URL usada naquela tentativa.

Numa entrega cancelada, o detalhe diz o motivo: o endpoint foi desativado, foi removido, ou outro endpoint foi cadastrado. Quando a entrega foi movida, o detalhe mostra para qual endpoint e o estado dela lá.

#Reenviar

Reenviar aparece no detalhe das entregas Falhou e Esgotado ou cancelado, menos nas que já foram movidas para outro endpoint. O reenvio entra na fila ("Reenvio na fila").

#Webhook padrão

Em Configurações → Integrações fica o Webhook padrão, usado quando um endpoint específico não está configurado. Veja Configurações.