Entenda os webhooks na Advanced Klaviyo Data Platform

O que você vai aprender

Saiba mais sobre webhooks e como você pode usá-los para enviar informações para seus aplicativos de terceiros em resposta a eventos capturados no Klaviyo. Para obter informações mais detalhadas sobre como receber webhooks do sistema, acesse nosso recurso para desenvolvedores sobre como trabalhar com webhooks do sistema.

This content requires Functional cookies to be enabled.

Update Cookie Settings

O que são webhooks?

Webhooks permitem que a Klaviyo transmita informações ou “chame” outros aplicativos, ferramentas e servidores por meio de solicitações HTTP. Eles podem enviar informações sobre um evento que aconteceu (por exemplo, um pedido feito, um novo cliente que se inscreveu etc.) ou notificar seus sistemas externos de que o evento ocorreu.

A Klaviyo oferece suporte a 2 tipos de webhook:

1. Webhook no Advanced Klaviyo Data Platform
   Os webhooks disponíveis como parte do Advanced Klaviyo Data Platform são usados para notificar seus sistemas externos de que um evento específico ocorreu e permitem que você envie informações em resposta a uma ampla variedade de eventos sem as limitações de estar em um fluxo.
2. Webhooks de fluxo
   Os webhooks de fluxo são ações dentro de fluxos. Eles enviam dados quando um perfil chega à ação de webhook e podem incluir informações sobre esse perfil ou sobre o evento que acionou o fluxo.

Principais componentes de webhooks

Os webhooks são compostos por alguns componentes principais:

• Tópico
  O evento que faz um webhook disparar
• Corpo (ou "o payload")
  Os dados que o webhook envia
• Cabeçalhos
  Um lugar para passar informações adicionais (como autenticação)

Como os webhooks na Advanced Klaviyo Data Platform diferem dos webhooks de fluxo?

Você pode usar webhooks no Advanced Klaviyo Data Platform ou webhooks de fluxo, dependendo das suas necessidades.

Eventos incluídos

Em fluxos acionados por métrica, os webhooks de fluxo só podem responder a eventos compatíveis como gatilhos de fluxo. Por exemplo, E-mail recebido e E-mail clicado não estão disponíveis no seletor de gatilho de métrica, enquanto cancelar inscrição do marketing por e-mail é compatível. Os webhooks do sistema no Advanced Klaviyo Data Platform permitem selecionar tópicos para eventos relacionados a mensagens, bem como eventos de integrações e das API da Klaviyo.

como:

• Eventos de e-mail (por exemplo, E-mail recebido, Clicou no e-mail, Marcou o e-mail como spam, cancelar inscrição do marketing por e-mail)
• Eventos de SMS (por exemplo, Sent SMS, Received SMS)
• notificação push de eventos (por exemplo, Received push, Bounced push)
• Eventos de integrações (ou seja, eventos de integrações próprias criadas pela Klaviyo)
• Eventos de API (por exemplo, eventos sincronizados por meio das APIs da Klaviyo)

Payload

Os webhooks de fluxo permitem que você personalize os dados da solicitação configurando um corpo JSON. Os webhooks do sistema no Advanced Klaviyo Data Platform usam um payload pré-criado com dados sobre os eventos que ocorreram. Uma única solicitação pode incluir vários eventos dos tópicos que você selecionou.

Limitações de fluxo

Os webhooks do fluxo seguem o acionador e as etapas do fluxo que os contém. Use fluxos separados para responder a diferentes acionadores de fluxo. A ação de webhook precisa estar Ativa para enviar solicitações automaticamente; uma ação em Rascunho não envia solicitações. Os webhooks do sistema são executados fora dos fluxos e podem inscrever-se em vários tópicos em 1 ponto de extremidade.

Configurar webhooks

1. Acesse Gerenciamento de dados > webhook na Klaviyo.
2. Clique em Criar webhook.
3. Na página Criar webhook, insira as seguintes informações:
   • Nome
     Como você vai identificar seu webhook
   • URL do ponto de extremidade
     A URL associada ao destino da solicitação de webhook
   • Chave secreta
     Insira uma chave secreta de 16–100 caracteres. A Klaviyo usa essa chave para assinar solicitações, para que o aplicativo que recebe possa verificar que elas vieram da Klaviyo.
   • Descrição
     Uma descrição opcional para o seu webhook.
4. Em Tópicos, selecione 1 ou mais tópicos que devem acionar notificações. Por exemplo, event:klaviyo.received_email corresponde a E-mail recebido.

5. Opcional: teste a conexão usando as etapas em Testar webhook do sistema abaixo antes de salvar.
6. Clique em Salvar para criar o webhook. O Klaviyo retorna você à página webhooks.

Após salvar, seu webhook aparece na página Webhooks com os seguintes detalhes:

• Nome do webhook
• URL do ponto de extremidade (encurtada por segurança)
• Status

Para parar de enviar notificações, abra o menu ao lado do webhook e selecione Desativar. Para remover, selecione Excluir e confirme a exclusão.

Testar webhooks do sistema

1. Depois de preencher os campos obrigatórios na página Criar webhook e selecionar seus tópicos, clique em Testar conexão.

2. No painel Testar webhook, selecione um tópico em Tópicos e clique em Testar para enviar uma solicitação de exemplo para o URL do seu ponto de extremidade.

3. Revise a mensagem para ver se o teste foi bem-sucedido. A guia Solicitação mostra os cabeçalhos e o payload enviados para o seu ponto de extremidade. A guia Resposta mostra os cabeçalhos, o corpo e o código de status da resposta do ponto de extremidade.

1. Clique em Cancelar para fechar o painel de teste e voltar à sua configuração de webhook.

Payload de exemplo

Abaixo está um exemplo de payload para uma solicitação acionada por E-mail recebido (event:klaviyo.received_email).

{
  "meta": {
    "timestamp": "2023-08-10T07:25:23.700369+00:00",
    "klaviyo_webhook_id": "ID",
    "version": "2024-06-28",
    "klaviyo_payload_id": "3843971dcfdee5083e6289e1bbdbb003e538b5a8a668fc43ae4f19d415ac18a2",
    "klaviyo_account_id": "ACCOUNT_ID"
  },
  "data": [
    {
      "topic": "event:klaviyo.received_email",
      "external_id": "ID",
      "payload": {
        "data": {
          "id": "ID",
          "type": "event",
          "links": {
            "self": "https://a.klaviyo.com/api/events/ID/"
          },
          "attributes": {
            "uuid": "96150200-374e-11ee-8001-a163313bc6c2",
            "datetime": "2023-08-10 07:21:56+00:00",
            "timestamp": 1691652116,
            "event_properties": {
              "$ESP": 0,
              "Subject": "? Free (Cool!) Swag Alert ?",
              "$message": "01H7F525FKR31P27Y7PNGVBBKK",
              "$event_id": "01H7F525FKR31P27Y7PNGVBBKK:125423419905414052533228990613763937641",
              "$group_ids": [
                "V7adxq"
              ],
              "$attribution": {
                "$send_ts": 0,
                "$attributed_event_id": ""
              },
              "Email Domain": "klaviyo-demo.com",
              "Campaign Name": "Daily Newsletter: 2023-08-10",
              "Inbox Provider": "Amazon SES Inbound",
              "$_cohort$message_send_cohort": "1691652081:01H7F525FKR31P27Y7PNGVBBKK"
            }
          },
          "relationships": {
            "metric": {
              "data": {
                "id": "ID",
                "type": "metric"
              },
              "links": {
                "self": "https://a.klaviyo.com/api/events/ID/relationships/metric/",
                "related": "https://a.klaviyo.com/api/events/ID/metric/"
              }
            },
            "profile": {
              "data": {
                "id": "ID",
                "type": "profile"
              },
              "links": {
                "self": "https://a.klaviyo.com/api/events/ID/relationships/profile/",
                "related": "https://a.klaviyo.com/api/events/ID/profile/"
              }
            }
          }
        }
      }
    }
  ]
}

Recursos adicionais