O que os webhooks fazem
Um webhook assina um evento específico da loja. Quando esse evento ocorre, a Storeep envia imediatamente os dados do evento para uma URL que você especificar (tipo API) ou para um endereço de e-mail que você informar (tipo E-mail). Webhooks são usados com frequência para integrações de rastreamento de pedidos, sincronização com CRM, conversões em plataformas de anúncios e notificações automáticas.
Para gerenciar webhooks, acesse Configurações → Webhooks. Você precisa da permissão de configurações para visualizar ou alterar webhooks.
Limites de webhook
- Máximo de 20 webhooks por loja. Tentar adicionar o 21º retorna o erro "Você atingiu o máximo de 20 webhooks por loja".
- A lista mostra os webhooks mais recentes primeiro, paginada em 40 por página.
Criando um webhook
Clique em Adicionar novo webhook, preencha os campos abaixo e depois clique em Adicionar.
Ativar
Marcado por padrão. Quando marcado, o webhook fica ativo assim que você salva e os eventos correspondentes são enviados. Desmarque para salvar o webhook desativado, sem receber nada. Você pode alternar isso a qualquer momento editando o webhook.
Nome
- Obrigatório. Máximo de 50 caracteres.
- Um rótulo descritivo exibido na lista, por exemplo Facebook CAPI pedido criado.
Tipo
- API: a Storeep envia uma solicitação HTTP POST com os dados do evento para sua URL.
- E-mail: a Storeep envia um e-mail com os dados do evento para seu endereço.
Evento
O evento da loja que dispara o webhook. Existem três eventos:
- Sessão criada: uma nova sessão de visitante é criada em sua loja.
- Pedido criado: um novo pedido é realizado.
- Pedido atualizado: o status ou dados de um pedido existente são alterados.
Importante: o tipo E-mail só entrega Pedido criado e Pedido atualizado. Se você escolher E-mail com Sessão criada, o webhook será salvo, mas nunca enviará nada. Use o tipo API se precisar do evento de sessão.
Formato
Apenas uma opção, Json: o payload é enviado como um documento JSON.
URL (somente tipo API)
- Obrigatório quando o tipo for API. Máximo de 500 caracteres.
- O campo exibe um prefixo
https://para você, então insira apenas o host e o caminho, por exemploapi.example.com/events/order. Se você colar um endereço completo comhttps://ouhttp://, o prefixo será removido antes de salvar. - Placeholders dinâmicos: insira qualquer campo dos dados do evento na URL usando a sintaxe de chaves duplas
{{field_name}}. Exemplo:example.com/postback?cid={{fbclid}}&payout={{order_total}}. Os valores são codificados para URL, e um placeholder cujo campo não exista resulta em valor vazio. Isso permite enviar dados de conversão direto para uma plataforma de anúncios sem proxy. - O endereço é validado após a remoção dos placeholders, então uma URL inválida retorna "A url que você inseriu está incorreta".
Endereço de e-mail (somente tipo E-mail)
- Obrigatório quando o tipo for E-mail. Deve ser um endereço válido, máximo de 127 caracteres.
Editando um webhook
Clique em qualquer linha para abrir o editor. Todos os campos são editáveis. O campo de URL só é preenchido quando o tipo salvo é API, e o campo de e-mail só é preenchido quando o tipo salvo é E-mail. Clique em Salvar para aplicar. Salvar com Ativar desmarcado desativa o webhook sem excluí-lo.
Colunas da lista de webhooks
- Nome: o rótulo com a data de criação.
- URL / E-mail: o destino.
- Tipo: API ou E-mail.
- Evento: Sessão criada, Pedido criado ou Pedido atualizado.
- Formato: Json.
- Status: Ativado ou Desativado.
Excluindo um webhook
Selecione uma ou mais linhas e clique em Excluir webhooks. A exclusão é permanente e interrompe todos os envios futuros para essa assinatura.
Entrega, tentativas e e-mails de falha
Esta seção se aplica aos webhooks do tipo API. Webhooks do tipo E-mail são enviados uma única vez, sem tentativas de reenvio e sem rastreamento de falhas.
Comportamento de tentativas
- Cada solicitação tem um tempo limite de 5 segundos. Se o destino retornar um erro 5xx, 429 (limite de taxa) ou não puder ser alcançado (erro de conexão), a entrega é tratada como falha temporária e será tentada novamente.
- Após a primeira falha, a Storeep tenta novamente com backoff exponencial em até 5 tentativas: cerca de 30s, 60s, 120s, 240s e depois 480s. Após a última tentativa, o evento é descartado.
- Uma resposta 4xx diferente de 429 (por exemplo, 404 ou 403) é tratada como falha permanente. A Storeep não tenta novamente, pois um endpoint incorreto ou rejeitado não se corrigirá sozinho.
- Se você tiver vários webhooks para o mesmo evento, a tentativa só reenvia para os que falharam. Endpoints que já retornaram sucesso são ignorados, evitando entregas duplicadas.
E-mail de notificação de falha
- A Storeep conta falhas consecutivas por webhook. Após 5 falhas consecutivas, o proprietário da loja recebe um e-mail com o título "Ação necessária: seu webhook Storeep está falhando", no idioma do proprietário, listando o nome do webhook, destino, evento e o último código de status HTTP.
- Você recebe exatamente um e-mail por sequência de falhas. Não serão enviados novos e-mails até que o webhook se recupere.
- Assim que uma entrega for bem-sucedida novamente, o contador de falhas é zerado e a notificação é rearmada, permitindo que uma futura sequência de falhas envie novo e-mail.
Dicas e armadilhas
- Você pode criar vários webhooks para o mesmo evento, por exemplo, enviar Pedido criado tanto para um CRM quanto para uma plataforma de anúncios como entradas separadas.
- Se seu endpoint exigir autenticação, coloque um token na query string da URL, seja fixo ou via
{{placeholder}}dos dados do evento, ou utilize um proxy que adicione a autenticação antes de encaminhar. - Sessão criada dispara para cada sessão única de visitante e pode ter alto volume em lojas movimentadas. Só assine esse evento se seu endpoint suportar o tráfego, e lembre-se de que só funciona com o tipo API.