5. Notificações

Configuração das preferências de webhooks

Os webhooks são as notificações enviadas pela Moip para seu sistema toda vez que sua transação passa por um evento e tem o seu status alterado. Sendo assim, através dos webhooks é possível sincronizar o seu sistema à Moip.

Para receber os webhooks você deve, primeiramente, criar uma preferência de notificação. É nesse momento que você vai cadastrar uma ou mais URLs para onde os webhooks serão enviados.

Atributos

Nome, descrição e tipo

events

Tipos de eventos das transações. Para saber mais visite a seção Eventos.

string list

target

URL de recebimento da notificação.

string

media

Tipo da notificação. Único valor possível: WEBHOOK.

string

id

Código identificador da preferência. Exemplo: NPR-DV61EEGGUFCQ

string(16)
response

token

Hash utilizado para assinar as notificações. O token será enviado em todas as notificações enviadas pela Moip para esta preferência.

string
response

Recebendo Webhooks

Para confirmar o recebimento de um webhook, o seu sistema deve retornar um código 2xx HTTP status. Informações retornadas no header ou no body serão ignoradas. Quaisquer respostas diferentes de 2xx serão interpretadas pela Moip como não recebimento do Webhook. Para estes casos, faremos uma retentativa de notificação conforme apresentado abaixo.

Retentativa

Descrição

1

Ocorre 10 segundos após o envio inicial

🚧

IMPORTANTE

Não podemos garantir a ordem dos status que serão recebidos pela sua aplicação. Desta forma, aconselhamos o uso da abordagem de tratamento de status baseado em hierarquia.

Melhores Práticas Para Trabalhar Com Webhooks

O uso de retentativas faz com que seja possível que você receba várias vezes a mesma notificação. Para proteger a sua aplicação, aconselhamos que você torne o processamento dos webhooks idempotent. Uma forma de fazer isso é logar o evento processado e garantir que outros eventos iguais sejam desconsiderados.

Para aumentar a segurança da sua aplicação e garantir que apenas a Moip pode enviar notificações para o seu sistema, você pode conferir o token enviado no header Authorization dos webhooks. Este token é o mesmo que é gerado no momento do cadastro da sua URL.