🔀 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 3 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?