🔀 Webhooks

Webhooks são uma forma de compartilhar informações de uma aplicação para outra, permitindo ampliar e integrar recursos sem a necessidade de uma integração nativa.

Escrito por Equipe Ensinio

Atualizado 5 meses atrás

Assim, você pode integrar a sua plataforma na Ensinio a outro sistema e automatizar o controle de seus produtos e usuários. As informações são condicionadas a eventos, e são enviadas quando um determinado evento acontece, seja um novo cadastro, compra aprovada ou até mesmo o pagamento recorrente bem-sucedido. O melhor é que você pode escolher quais eventos deseja receber.

Assista ao vídeo:

Como integrar sua plataforma com webhooks?

Antes de explicar como você intrega aplicações via webhooks é importante que você sabia o quanto essa ferramenta é poderosa. Sabe aquela lista de leads que todo dia se cadastram na sua plataforma e que você precisa copiar manualmente um por um e adicionar no seu CRM? Com a integração utilizando Webhooks você pode automatizar esses e vários outros processos, como emitir uma nota fiscal, adicionar um usuário na base da de dados e disparar um e-mail utilizando Integromat, Pluga, Zapier ou outra plataforma da sua preferência. As possibilidades são inúmeras e você só precisa criar a configuração uma única vez. Maravilhoso, né?

Não precisa se preocupar, integrar via Webhooks é bem simples, você precisa ter um link para onde as informações serão enviadas quando um evento selecionado ocorrer e criar uma configuração escolhendo quais eventos você deseja ser notificado. Você precisa realizar esses dois passos:

1 - Criar uma entidade externa (endpoint/link) para receber as informações;

2 - Criar uma configuração, escolhendo os eventos, produtos e informando a URL.

Criando uma configuração

Para criar uma configuração você precisa acessar sua conta no painel administrativo com as informações de login e senha. Em seguida, siga os seguintes passos:

Acesse a seção de Ferramentas no menu lateral à esquerda;
Clique em Webhook -> Webhooks;
Preencha as informações:
- Nome da configuração;
- Informe a URL que irá receber receber as informações;
- Defina se o evento está condicionado ao usuário ou a um pedido;
- Para pedidos, matrículas ou assinaturas, você pode selecionar receber os eventos de um item específico ou de todos os grupos de produtos.
- Selecione os eventos;
- Defina se a configuração está ativa;
Clique em salvar.

Depois que tudo estiver configurado você pode testar, enviaremos informações fictícias para cada um dos eventos selecionados, e verificar se tudo ocorreu como esperado. Em Ferramentas -> Webhook -> Históricos Webhooks você pode acompanhar o status dos eventos disparados. Se tudo ocorreu como esperado o status estará “200 - Ok”, qualquer outro status iniciado com um número diferente de 2 significa que ocorreu um erro no processo, as informações não foram recebidas. Não se preocupe! Você pode reenviar o evento quantas vezes forem necessárias.

Reenviando um evento

Para reenviar um evento você precisa acessar sua conta no painel administrativo com as informações de login e senha. Em seguida, siga os seguintes passos:

Acesse a seção de Ferramentas no menu lateral à esquerda;
Clique em Webhook -> Históricos dos webhooks;
Selecione qual(is) evento(s) que deseja reenviar;
Selecione a ação Reenviar dados que aparecerá na acima das colunas;
Clique no ícone de play.

Se tudo ocorreu como esperado o status estará “200 - Ok”, qualquer outro status iniciado com um número diferente de 2 significa que ocorreu um erro no processo e você pode reenviar o(s) evento(s). Lembrando que o erro está relacionado a entidade externa. Em casos de erro, indicamos verificar se está tudo certo com a entidade externa que irá receber os dados e depois reenviar o evento.

Resposta da requisição HTTP

O envio de informações usando webhooks usa o protocolo de comunicação para sistemas HTTP, após o envio dos dados você pode checar se tudo ocorreu como esperado verificando o status da requisição. Os códigos de status são agrupados em cinco grupos:

100 - 199 : São informativos;
200 - 299: Respostas de sucesso;
300 - 399: Redirecionamento;
400 - 499: Erro do cliente;
500 - 599: Erro de servidor.

Aqui estão alguns dos principais erros que podem acontecer:

Erro 403 - Forbidden (Proibido)

Erro 403 significa que a solicitação foi recebida, mas o recebedor se recusou a atendê-la, assim negando-a. Esse erro pode ocorrer caso não tenha permissão para realizar a solicitação ou a chave de verificação (token) não estiver correta.

Erro 404 - Not Found (Não encontrado)

Erro 404 significa que a URL configurada para receber os dados não existe.

Erro 500 - Internal Server Error (Erro do Servidor Interno)

Erro 500 significa que a solicitação não foi compreendida. Os motivos podem ser vários, este erro acontece quando não é possível especificar o erro real que ocorre durante a solicitação, o mais comum é rota não encontrada.

Erro 503 - Service unavailable (Serviço indisponível)

Erro 503 significa que a solicitação não foi atendida pelo recebedor (entidade externa que recebe as informações), podendo estar indisponível por recursos insuficientes ou simplesmente um problema com o servidor.

Pronto, agora que você já tem tudo configurado, entendeu como acompanhar os eventos enviados e os possíveis status, agora é só se concentrar com as vendas!

Eventos

Novo cadastrado na plataforma

Você receberá dados sobre os novos usuários que se cadastraram na sua plataforma..

Parâmetro	Descrição
token	Sua plataforma na Ensinio possui um token de segurança. Todas as informações enviadas via webhooks contém no cabeçalho da requisição HTTP o token para estabelecer maior nível de segurança. Você pode utilizar esse token para validar se a requisição foi feita da sua plataforma na Ensinio, evitando fraudes.
event	Evento disparado, que neste caso é new_register.
user	Dados do novo usuário.
user.id	Identificador único do usuário.
user.email	E-mail do usuário.
user.phone	Telefone do usuário.
user.username	Identificação do usuário na plataforma.
user.full_name	Nome completo do usuário.
user.first_name	Primeiro nome do usuário.
user.last_name	Sobrenome do usuário.
user.display_name	Nome do usuário exibido na plataforma.

Nova seção no checkout

Você receberá dados relacionados às novas seções no checkout sempre que um possível comprador acessar a página de pagamento, contendo informações sobre o possível cliente e do produto. Este evento é disparado sempre que um possível comprador entra na página de pagamento, incluindo aqueles que finalizaram a compra.

Parâmetro	Descrição
token	Sua plataforma na Ensinio possui um token de segurança. Todas as informações enviadas via webhooks contém no cabeçalho da requisição HTTP o token para estabelecer maior nível de segurança. Você pode utilizar esse token para validar se a requisição foi feita da sua plataforma na Ensinio, evitando fraudes.
event	Evento disparado, que neste caso é begin_checkout.
user	Dados do possível comprador
user.id	Identificador único do possível comprador.
user.email	E-mail do possível comprador.
user.phone	Telefone do possível comprador.
user.username	Identificação do possível comprador na plataforma.
user.full_name	Nome completo do possível comprador.
user.first_name	Primeiro nome do possível comprador.
user.last_name	Sobrenome do possível comprador.
user.display_name	Nome do possível comprador exibido na plataforma.
product	Dados do produto que o possível comprador possui interesse.
product.id	Identificador único do produto.
product.slug	Parte da URL do produto.
product.price	Preço do produto.
product.title	Título do produto.
product.className	Tipo do produto, podendo ser: course (curso), media_space(conteúdo do media space), bundle (pacote) ou um plan (plano)
product.authors	Dados dos autores do produto.
product.authors.id	Identificador único do autor.
product.authors.email	E-mail do autor.
product.authors.photo	URL da foto do autor.
product.authors.username	Identificação do autor na plataforma.
product.authors.full_name	Nome completo do autor.
product.authors.first_name	Primeiro nome do autor.
product.authors.last_name	Sobrenome do autor.
product.authors.display_name	Nome do autor exibido na plataforma.

Pedidos

Você receberá dados relacionados às suas vendas, contendo informações sobre cliente, produto e pagamento. Sempre que houver alguma alteração com o status do pedido e o evento estiver selecionado, você será notificado.

Parâmetro	Descrição
token	Sua plataforma na Ensinio possui um token de segurança. Todas as informações enviadas via webhooks contém no cabeçalho da requisição HTTP o token para estabelecer maior nível de segurança. Você pode utilizar esse token para validar se a requisição foi feita da sua plataforma na Ensinio, evitando fraudes.
event	Evento disparado, que podem ser: expired (expirado), refused (recusado), approved (aprovado), refunded (reembolsado), chargeback ou waiting_payment (aguardando pagamento).
order	Dados do pedido.
order.uuid	Identificador único do pedido.
order.order_status	Status do pedido, que podem ser: aproved (aprovado), pending (pendente) ou canceled (cancelado).
order.coupon_code	Código do cupom utilizado na compra.
order.coupon_discount	Valor do desconto aplicado no pedido.
order.paid_amount	Valor total do pedido, incluindo todas as transações pagas.
product	Dados do produto.
product.slug	Parte da URL do produto adquirido.
product.price	Preço do produto adquirido.
product.title	Título do produto adquirido.
product.className	Tipo do produto, podendo ser: course (curso), media_space(conteúdo do media space), bundle (pacote) ou um plan (plano).
product.authors	Dados dos autores do produto adquirido.
product.authors.id	Identificador único do autor.
product.authors.email	E-mail do autor.
product.authors.photo	URL da foto do autor.
product.authors.username	Identificação do autor na plataforma.
product.authors.full_name	Nome completo do autor.
product.authors.first_name	Primeiro nome do autor.
product.authors.last_name	Sobrenome do autor.
product.authors.display_name	Nome do autor exibido na plataforma.
customer	Dados do comprador.
customer.name	Nome do comprador.
customer.email	E-mail do comprador.
customer.phone	Telefone do comprador.
customer.document	Documento do comprador.
customer.full_name	Nome completo do comprador.
customer.first_name	Nome do comprador.
customer.last_name	Sobrenome do comprador.
transaction	Dados da transação.
transaction.id	Identificador único do pedido.
transaction.date	Data em que a transação foi efetuada.
transaction.paid_amount	Valor total da transação, incluindo taxas e juros.
transaction.payment_method	Método de pagamento utilizado pelo comprador. Os valores podem ser: credit_card (cartão de crédito) ou billet (boleto bancário).
transaction.address	Endereço completo do comprador
transaction.installment	Número de parcelas escolhidas pelo comprador. Para compras cujo método de pagamento é credit_card (cartão de crédito), as parcelas podem variar de 1 a 12. Quando o método de pagamento é billet (boleto bancário) a informação será NULL.
transaction.card	Dados do cartão de crédito. Estas informações só serão enviadas quando o método de pagamento for cartão de crédito.
transaction.card.card_brand	Bandeira do cartão de crédito utilizado pelo comprador.
transaction.card.card_holder_name	Nome do titular do cartão impresso no cartão.
transaction.card.card_first_digits	Primeiros dígitos do cartão de crédito.
transaction.card.card_last_digits	Últimos dígitos do cartão de crédito.
transaction.billet	Dados do boleto bancário. Estas informações só serão enviadas quando o método de pagamento for boleto bancário.
transaction.billet.barcode	Código de barras do boleto.
transaction.billet.billet_link	Link do boleto.
transaction.billet.expire_date	Data de expiração do boleto.
transaction.transaction_status	Status da transação, que podem ser: paid (pago), waiting_payment (aguardando pagamento), refunded (reembolsado), refused (recusado), refunded (reembolsado) ou chargeback (contestação ou reversão do pagamento).
invoice_data	Dados para emissão da nota fiscal.
invoice_data.date	Data do processamento.
invoice_data.email	E-mail do comprador.
invoice_data.phone	Telefone do comprador.
invoice_data.document	Documento do comprador.
invoice_data.full_name	Nome completo do comprador.
invoice_data.full_address	Endereço completo do comprador
invoice_data.product	Nome do produto adquirido.
invoice_data.amount	Valor da transação.
invoice_data.address	Dados do endereço do comprador
invoice_data.address.city	Cidade do comprador.
invoice_data.address.state	Estado do comprador.
invoice_data.address.street	Rua do comprador.
invoice_data.address.country	Pais do comprador.
invoice_data.address.zipcode	CEP do comprador.
invoice_data.address.neighborhood	Bairro do comprador.
invoice_data.address.complementary	Complemento do endereço do comprador.
invoice_data.address.street_number	Número da residência do comprador.
invoice_data.address.uf_ibge	Número do estado do comprador pelo IBGE.
invoice_data.address.city_ibge	Número da cidade do comprador pelo IBGE.

Exemplo dos eventos no formato JSON

Novo cadastrado na plataforma

{

"user": {

"id": 75,

"email": "rafael@teste.com",

"phone": "+(42) 98194-1922",

"username": "rafaelvieira",

"full_name": "Rafael Vieira",

"last_name": "Vieira",

"first_name": "Rafael",

"display_name": "RafaelVieira"

"event": "new_register"

}

Nova seção no checkout

{

"user": {

"id": 26,

"email": "josefina@teste.com",

"phone": "+(86) 2327-1205",

"username": "josefinade oliveira",

"full_name": "Josefina de Oliveira",

"last_name": "de Oliveira",

"first_name": "Josefina",

"display_name": "Josefinade Oliveira"

"event": "begin_checkout",

"product": {

"slug": "do-zero-ao-avancado",

"price": 8643.3,

"title": "Do zero ao Avançado",

"authors": [

{

"id": 30,

"email": "luisguibelem@teste.com",

"photo": "",

"username": "luis_guibelem",

"full_name": "Luis Guilherme",

"last_name": "Guilherme",

"first_name": "Luis",

"display_name": "Luis Guilherme"

}

"className": "Pacote"

}

Pedidos

{

"event": "approved",

"order": {

"uuid": 5170247,

"coupon_code": "xcsta",

"paid_amount": 5194.91,

"order_status": null,

"coupon_discount": 3255

"product": {

"slug": "construindo-produtos-digitais",

"price": 8449.91,

"title": "Construindo produtos digitais",

"authors": [

{

"id": 30,

"email": "luisguibelem@teste.com",

"photo": "",

"username": "luis_guibelem",

"full_name": "Luis Guilherme",

"last_name": "Guilherme",

"first_name": "Luis",

"display_name": "Luis Guilherme"

}

"className": "Curso"

"customer": {

"name": "Santiago Gomes",

"email": "santiago@teste.com",

"phone": "(62) 2794-0479",

"document": "40304533122",

"full_name": "santiago gomes",

"last_name": "Gomes",

"first_name": "Santiago"

"transaction": {

"id": 97,

"card": {

"card_brand": "elo",

"card_holder_name": "Elizabeth Santos",

"card_last_digits": 2834,

"card_first_digits": 5739

"date": "2022-07-28",

"address": "Rua Alfredo Cruz, 95, Centro, Boa Vista, RR - br. 69301-140",

"paid_amount": 5194.91,

"installments": 2,

"payment_method": "credit_card",

"transaction_status": "paid"

"invoice_data": {

"date": "2022-07-28",

"email": "santiago@teste.com",

"phone": "6292794-0479",

"amount": 5194.91,

"address": {

"city": "Boa Vista",

"state": "RR",

"street": "Rua Alfredo Cruz",

"country": "Brasil",

"uf_ibge": "14",

"zipcode": "69301-140",

"city_ibge": "1400100",

"neighborhood": "Centro",

"complementary": "casa",

"street_number": "95"

"product": "Construindo produtos digitais",

"document": "40304533122",

"full_name": "Santiago Gomes",

"full_address": "Rua Alfredo Cruz, 95, Centro, Boa Vista, RR - br. 69301-140"

}

Esse artigo foi útil?