Configurar webhooks

O que é

Webhooks são solicitações HTTPS que a YCloud envia para o seu aplicativo quando a entrega de mensagens, mensagens recebidas, contatos, modelos, chamadas e outros recursos são alterados.

Antes de começar

Armazene sua chave de API da YCloud em YCLOUD_API_KEY.
Implante um endpoint HTTPS publicamente acessível.
Preserve o corpo bruto da solicitação para verificação de assinatura.
Decida quais tipos de eventos seu aplicativo precisa.

Como funciona

Crie um endpoint de Webhook e inscreva-o nos tipos de evento.
Armazene o secret do endpoint retornado.
A YCloud envia uma solicitação de evento para o seu endpoint.
Verifique o YCloud-Signature antes de confiar na solicitação.
Retorne uma resposta 2xx prontamente.
Processe o evento de forma idempotente, pois a entrega pode ser repetida.

Solicitação

Crie um endpoint com POST /webhookEndpoints.

Campos da solicitação

Campo	Obrigatório	Descrição
`url`	Sim	URL HTTPS pública que recebe solicitações de evento. Máximo de 500 caracteres.
`enabledEvents`	Sim	Tipos de eventos entregues a este endpoint.
`eventProperties`	Condicional	Propriedades incluídas para tipos de eventos selecionados. Obrigatório para `contact.attributes_changed`.
`description`	Não	Descrição do endpoint. Máximo de 400 caracteres.
`status`	Não	Status inicial do endpoint.

Exemplo de solicitação

curl --request POST https://api.ycloud.com/v2/webhookEndpoints \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/ycloud",
    "enabledEvents": [
      "whatsapp.inbound_message.received",
      "whatsapp.message.updated",
      "sms.message.updated"
    ],
    "description": "Production messaging events"
}'

Inscrever-se em eventos de echo e handover

Para Agents integrados por meio da API REST pública, crie um endpoint com as seguintes inscrições. Agents criados no Console não emitem esses três eventos. Para alterar um endpoint existente, preserve todas as inscrições de eventos de que você ainda precisa.

curl --request POST https://api.ycloud.com/v2/webhookEndpoints \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/ycloud",
    "enabledEvents": [
      "whatsapp.echo_message.created",
      "whatsapp.echo_message.updated",
      "whatsapp.meta_business_agent.handover.updated",
      "whatsapp.inbound_message.received"
    ],
    "description": "API Agent echo and handover events"
  }'

Os dois tipos de eventos de echo contêm uma carga útil whatsappMessage no formato de mensagem padrão. O evento de handover contém whatsappMetaBusinessAgent e mantém suas informações de Agent/controle. Eles não usam o contrato whatsapp.smb.message.echoes do WhatsApp Business App. Consulte os detalhes dos eventos de echo e handover para definições de campos, exemplos, ordenação e limites de correlação de handover.

Inscrever-se em eventos de mensagens do Messenger

Tipo de evento	Carga útil	Quando ocorre
`messenger.inbound_message.received`	`messengerInboundMessage`	Um cliente envia uma mensagem de texto comum.
`messenger.inbound_message.updated`	`messengerInboundMessage`	Um cliente edita uma mensagem de texto recebida e armazenada.
`messenger.message.updated`	`messengerMessage`	Um resultado de envio de saída ou uma confirmação de mensagem correspondente está disponível.
`messenger.message_reaction.updated`	`messengerMessageReaction`	Um cliente reage a uma mensagem ou retira uma reação dela.

Inclua os nomes dos eventos necessários em enabledEvents ao criar ou atualizar um endpoint. Por exemplo, inscreva-se em todos os quatro com:

{
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": [
    "messenger.inbound_message.received",
    "messenger.inbound_message.updated",
    "messenger.message.updated",
    "messenger.message_reaction.updated"
  ]
}

No Dashboard, um novo endpoint começa sem nenhum evento selecionado. Selecionar a categoria Messenger seleciona seus eventos disponíveis, incluindo edições e reações. Você pode desmarcar eventos individuais em seguida. As inscrições existentes não incluem automaticamente eventos de edição ou reação adicionados recentemente. Preserve todas as inscrições de que você ainda precisa ao atualizar um endpoint. Uma edição mantém o mesmo messengerInboundMessage.id e metaMessageId, substitui text.body e adiciona editCount e editTime. Os campos sendTime e createTime da mensagem permanecem inalterados; o envelope do evento createTime é o horário da edição. Mensagens não editadas omitem os campos de edição. Apenas uma mensagem recebida existente é atualizada. Edições mais antigas são ignoradas; mensagens ausentes e edições históricas não são reconstruídas. Correlacione as atualizações pelo ID da mensagem e use a contagem cumulativa para evitar aplicar um texto mais antigo sobre uma versão mais nova. Tentativas repetidas da origem podem criar outro ID de evento para a mesma edição salva. Consulte o exemplo de edição de mensagem recebida. Os eventos de reação contêm pageId, o psid do cliente que reagiu, o alvo metaMessageId e a ação action (react ou unreact). Os campos opcionais reaction e emoji podem estar ausentes, especialmente para unreact. Uma reação não altera o estado de entrega de uma mensagem. A mensagem de destino pode ser originada fora da API da YCloud, de modo que o evento não exige um registro local de mensagem nem inclui um ID de mensagem local. O campo createTime do evento retém o horário da interação de origem. Novas tentativas de entrega de um cliente mantêm o id e a carga útil do evento. O processamento de retornos da origem pode produzir outro ID de evento para uma interação repetida; não trate IDs de eventos como identidades de reações ou mensagens. Consulte os exemplos de carga útil de reação para ambas as ações.

Resposta

A resposta retorna o endpoint criado e seu segredo de assinatura secret. Armazene o segredo com segurança. A YCloud o utiliza para gerar assinaturas de Webhook.

Exemplo de resposta

{
  "id": "WEBHOOK_ENDPOINT_ID",
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": [
    "whatsapp.inbound_message.received",
    "whatsapp.message.updated",
    "sms.message.updated"
  ],
  "description": "Production messaging events",
  "status": "active",
  "secret": "whsec_REPLACE_WITH_RETURNED_SECRET",
  "createTime": "2026-07-16T12:00:00.000Z",
  "updateTime": "2026-07-16T12:00:00.000Z"
}

Campos de resposta

Campo	Descrição
`id`	ID do endpoint de Webhook usado para recuperar, atualizar, excluir ou alternar o segredo do endpoint.
`url`	URL de destino para a entrega do evento.
`enabledEvents`	Tipos de eventos habilitados atualmente.
`status`	Estado atual do endpoint.
`secret`	Segredo usado para verificar `YCloud-Signature`. Armazene-o com segurança.
`createTime`, `updateTime`	Carimbos de data/hora do endpoint no formato RFC 3339.

Receber eventos

Requisição do evento

A YCloud envia um objeto de evento JSON para o url configurado. O evento inclui campos comuns como id, type, apiVersion e createTime, além de um payload específico para o tipo. Seu handler deve:

Ler o corpo bruto da requisição.
Validar o cabeçalho YCloud-Signature com o segredo do endpoint antes de confiar no payload.
Retornar uma resposta 2xx com sucesso prontamente.
Mover processamentos lentos para uma fila.
Tornar o processamento do evento idempotente para que entregas repetidas não repitam ações de negócios.

Não analisar (parse) nem modificar o corpo da requisição antes da validação da assinatura. Use exatamente os bytes brutos recebidos pelo seu servidor.

Resposta do receptor

Retorne uma resposta HTTP 2xx de sucesso assim que a assinatura e a requisição forem aceitas. O corpo da resposta pode ser vazio.

HTTP/1.1 204 No Content

Mova o processamento de negócios lento para uma fila. Um tempo limite esgotado (timeout) ou uma resposta que não seja 2xx pode fazer com que a YCloud tente reenviar o evento, portanto faça a desduplicação pelo id do evento.

Exemplos comuns de payload

Expanda um evento para inspecionar o exemplo de payload completo. Esses exemplos vêm da especificação OpenAPI para webhooks. Consulte todos os exemplos de payload de webhook para cada tipo de evento suportado.

Evento de atributos de contato alterados

Exemplo de payload quando os atributos de contato são alterados

{
  "id": "evt_1234567890",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "nickName": {
        "oldValue": "John Doe",
        "newValue": "Johnny Doe"
      },
      "email": {
        "oldValue": "john.doe@example.com",
        "newValue": "johnny.doe@example.com"
      },
      "tags": {
        "oldValue": [
          "premium",
          "newsletter"
        ],
        "newValue": [
          "premium",
          "newsletter",
          "vip"
        ],
        "extra": [
          {
            "action": "ADDED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

Evento de contato criado

Exemplo de payload quando um novo contato é criado

{
  "id": "evt_2345678901",
  "type": "contact.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactCreated": {
    "id": "1824266594102064128",
    "nickName": "John Doe",
    "realName": "John Smith",
    "phoneNumber": "+16315551111",
    "countryCode": "US",
    "countryName": "United States",
    "email": "john.doe@example.com",
    "sourceType": "api",
    "sourceId": "import_batch_123",
    "sourceUrl": "https://example.com/signup",
    "lastSeen": "2024-01-01T11:59:00.000Z",
    "lastConnectedNumber": "+16315552222",
    "ownerEmail": "owner@example.com",
    "tags": [
      "premium",
      "newsletter"
    ],
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "blocked": false,
    "customAttributes": {
      "attr1": "value1",
      "attr2": "value2",
      "attr3": 123
    }
  }
}

Evento de contato excluído

Exemplo de payload quando um contato é excluído

{
  "id": "evt_3456789012",
  "type": "contact.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactDeleted": {
    "id": "1824266594102064128",
    "nickName": "John Doe",
    "phoneNumber": "+16315551111",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Evento de cancelamento de assinatura pelo cliente

Exemplo de payload quando um cliente cancela a assinatura

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Cliente retoma assinatura

Exemplo de payload quando um cliente retoma a assinatura

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Evento de modelo do WhatsApp arquivado

Exemplo de payload quando um modelo do WhatsApp é arquivado

{
  "id": "evt_template_archived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "statusUpdateEvent": "ARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Evento de modelo do WhatsApp desarquivado

Exemplo de payload quando um modelo do WhatsApp é desarquivado. O status do modelo é o status atual retornado pela Meta e não representa uma nova análise de aprovação.

{
  "id": "evt_template_unarchived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "statusUpdateEvent": "UNARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

Evento de chamada do WhatsApp conectada

Exemplo de payload quando uma chamada do WhatsApp é conectada

{
  "id": "evt_call_connect_123",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "callingConnect": {
    "id": "6757b723960b25543b9ecc66",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEF",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "dialTime": 1733826430000,
    "sdpType": "offer",
    "sdp": "v=0\r\no=- 1732169627243 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS af3b01e3-eb42-4244-812e-db903c062ae7\r\na=ice-lite\r\nm=audio 3480 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 31.13.87.130\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:785588535 1 udp 2122260223 31.13.87.130 3480 typ host generation 0 network-cost 50\r\na=candidate:1906600321 1 udp 2122262783 2a03:2880:f217:d0:face:b00c:0:699c 3480 typ host generation 0 network-cost 50\r\na=ice-ufrag:CvRXRnInnWhQzLIE\r\na=ice-pwd:HGXUGAFI8wK6seuVknBT2Q==\r\na=fingerprint:sha-256 FB:56:A1:C5:37:35:6C:5C:1B:05:23:B0:DD:BB:2E:C9:5F:E4:70:61:7B:D9:1D:09:84:76:46:23:12:38:B7:01\r\na=setup:actpass\r\na=mid:audio\r\na=sendrecv\r\na=msid:af3b01e3-eb42-4244-812e-db903c062ae7 WhatsAppTrack1\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=maxptime:20\r\na=ptime:20\r\na=ssrc:659928310 cname:WhatsAppAudioStream1\r\n"
  }
}

Evento de chamada do WhatsApp encerrada

Exemplo de payload quando uma chamada do WhatsApp é encerrada

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEFENjB",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

Evento de status da chamada do WhatsApp atualizado

Exemplo de payload quando o status de uma chamada do WhatsApp é atualizado

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "status": "RINGING",
    "recipientPhone": "+6281361905133"
  }
}

Consulte Payloads de eventos de webhook para obter o esquema Event completo e a referência interativa de payloads.

Alternar o segredo do endpoint

Alterne um segredo se ele for exposto ou como parte de sua política de segurança:

curl --request POST \
  https://api.ycloud.com/v2/webhookEndpoints/WEBHOOK_ENDPOINT_ID/rotateSecret \
  --header "X-API-Key: $YCLOUD_API_KEY"

Implemente o novo segredo no seu receptor imediatamente após a alternância.

Um endpoint que falha repetidamente ao receber notificações pode mudar para o status pending e parar de receber eventos. Monitore as falhas de webhook e o status do endpoint.

Para obter o código de verificação de assinatura, intervalos de nova tentativa e implementação do receptor, consulte Implementar um receptor de webhook.

Primeiros passos

Guias

Endpoints

Webhooks

O que é

Antes de começar

Como funciona

Solicitação

Campos da solicitação

Exemplo de solicitação

Inscrever-se em eventos de echo e handover

Inscrever-se em eventos de mensagens do Messenger

Resposta

Exemplo de resposta

Campos de resposta

Receber eventos

Requisição do evento

Resposta do receptor

Exemplos comuns de payload

Alternar o segredo do endpoint

​O que é

​Antes de começar

​Como funciona

​Solicitação

​Campos da solicitação

​Exemplo de solicitação

​Inscrever-se em eventos de echo e handover

​Inscrever-se em eventos de mensagens do Messenger

​Resposta

​Exemplo de resposta

​Campos de resposta

​Receber eventos

​Requisição do evento

​Resposta do receptor

​Exemplos comuns de payload

​Alternar o segredo do endpoint

O que é

Antes de começar

Como funciona

Solicitação

Campos da solicitação

Exemplo de solicitação

Inscrever-se em eventos de echo e handover

Inscrever-se em eventos de mensagens do Messenger

Resposta

Exemplo de resposta

Campos de resposta

Receber eventos

Requisição do evento

Resposta do receptor

Exemplos comuns de payload

Alternar o segredo do endpoint