8. Notificações

Configuração das preferências de notificação e webhooks

Os webhooks são as notificações enviadas pelo Moip para seu sistema toda vez que sua transação tem o 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

Detalhes

events

Tipos de eventos da mudança de status

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.

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 re-tentativa automáticaa conforme apresentado abaixo.

Retentativa

Descrição

Ocorre 10 segundos após o envio inicial.

🚧

IMPORTANTE

1. 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.

2. Para Plataformas e Marketplaces que estejam integrados por meio do Moip Connect , o cadastro das URLs deve ser realizado por meio das configurações do Aplicativo .

Melhores Práticas Para Trabalhar Com Webhooks

O uso de retentativas e a possibilidade de reenvio manual de webhooks 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 dos webhooks. Este token é o mesmo que é gerado no momento do cadastro da sua URL.