receptionworksAjuda

Integrações e webhooks

Envie conversas, reservas, pedidos à equipa e pedidos de apoio para o Zapier, o Make ou o seu servidor; verifique a assinatura e os envios.

As integrações enviam os eventos da empresa para outro serviço assim que acontecem: uma nova conversa, uma reserva, o pedido de um membro da equipa, um pedido de apoio. Com o Zapier ou o Make pode, por exemplo, adicionar uma linha a uma folha de cálculo, enviar uma mensagem para um chat ou criar uma ficha num CRM sem copiar os dados à mão.

Onde encontrar

Abra «Módulos» no menu superior, ligue o módulo «Integrações» (por predefinição está desativado) e clique em «Abrir integrações» no respetivo cartão. Abre-se o separador «Webhooks», com o separador «Registo de eventos» ao lado. Só Proprietário e Administrador podem abrir a secção: o endereço de um destino pode conter um token privado. Enquanto o módulo estiver desativado, nada é entregue e os eventos ocorridos entretanto não são reenviados depois. Os destinatários continuam configurados e o registo de eventos continua a ser mantido.

Como adicionar um destino

  1. No Zapier, crie um Zap com o acionador «Webhooks by Zapier» e o evento «Catch Hook» e copie o endereço fornecido. No Make, adicione o módulo «Custom webhook» e copie o respetivo endereço.
  2. Na página de integrações, preencha «Nome» (por exemplo, o nome do Zap) e «Endereço do destino» (o endereço copiado).
  3. Em «Eventos a enviar», assinale o que deve ser enviado.
  4. Clique em «Adicionar destino».
  5. O segredo de assinatura aparece uma única vez. Copie-o e guarde-o em segurança. O Zapier e o Make não precisam dele; o seu próprio servidor usa-o para verificar a assinatura. Se o perder, crie um novo com «Alterar o segredo».
  6. Na ficha do destino, clique em «Enviar teste». O resultado é Entregue ou Não entregue, com o motivo.

O endereço tem de ser público e começar por https. São recusados, com o motivo indicado: endereços http, endereços IP em vez de um domínio, portas personalizadas, endereços com utilizador e palavra-passe, endereços internos e endereços de domínios do ReceptionWorks. A página mostra apenas o domínio e o caminho: a parte depois do ponto de interrogação pode conter o token do seu destino.

Que eventos são enviados

Os eventos do chat de teste não são enviados. Um destino recebe apenas os eventos ocorridos depois de adicionado e enquanto está ativo: o que acontece durante uma pausa ou desativação não é enviado mais tarde.

«Nova mensagem» e «Conversa completa» levam o texto integral das conversas, incluindo o que os clientes escrevem. O texto sai da ReceptionWorks e chega ao destino que escolher, por isso assinale-os apenas para destinos em que confia. Um destino novo começa com estes dois desmarcados. Só são enviados enquanto algum destino os tiver marcados e não aparecem no registo de eventos nem na sua exportação: a própria conversa está na caixa de entrada. As conversas de teste e os clientes bloqueados não são enviados.

O que o destino recebe

Cada evento é um pedido POST com um corpo JSON. Exemplo de um pedido de um membro da equipa feito por um funcionário de IA:

{
  "schema_version": "business-webhook.v1",
  "id": "5b0c5e2e-0000-4000-8000-000000000001",
  "type": "conversation.handoff_requested",
  "occurred_at": "2026-10-07T09:30:00.000Z",
  "business": { "name": "Example Studio" },
  "actor": { "kind": "ai_employee" },
  "channel": "telegram",
  "employee": { "name": "Anna" },
  "conversation": { "url": "https://app.example.com/businesses/studio/inbox?conversation=example" },
  "customer": { "name": "Maria", "email": "maria@example.com", "phone": "+1 555 0100" },
  "booking": null,
  "handoff": { "reason": "ai_request", "reason_text": "The customer wants to discuss a discount" },
  "support_case": null
}

As secções que não se aplicam ao evento são null. O evento de «Enviar teste» tem o tipo webhook.test e todas as secções exceto business são null. Os dados não têm texto traduzido: os nomes são como foram guardados, os códigos são palavras inglesas fixas e as horas estão em UTC.

"message": {
  "id": "6c1d0f52-0000-4000-8000-000000000002",
  "sequence": 12,
  "author": "customer",
  "text": "Hello, can I book for Friday?",
  "created_at": "2026-10-07T09:29:41.000Z",
  "attachments": [{ "kind": "image", "name": "photo.jpg", "media_type": "image/jpeg" }]
}

As mensagens e as transcrições podem chegar fora de ordem e repetir-se, por isso não conte com a ordem de chegada. Use sequence para repor a ordem das mensagens de uma conversa e descarte a entrega cujo webhook-id já processou. A transcrição repete mensagens que talvez já tenha recebido uma a uma: use-a para verificar ou reconstruir toda a conversa.

Como verificar a assinatura

Cada pedido traz três cabeçalhos do padrão Standard Webhooks: webhook-id, webhook-timestamp e webhook-signature. O Zapier e o Make não os verificam. No seu servidor, use a biblioteca oficial Standard Webhooks para a sua linguagem: passe-lhe o segredo tal como é mostrado (começa por whsec_), o corpo original sem alterações e os três cabeçalhos. Verificação manual:

signed_content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature      = "v1," + base64( HMAC-SHA256( key, signed_content ) )
key            = base64-decoded part of the secret after "whsec_"

O cabeçalho webhook-signature contém v1, e a assinatura. Depois de «Alterar o segredo» contém duas assinaturas separadas por um espaço: aceite o pedido se uma delas coincidir. Rejeite pedidos cuja marca de tempo difira do seu relógio mais de cinco minutos.

Novas tentativas e desativação automática

O destino tem de responder com um código 2xx em 10 segundos. Os redirecionamentos não são seguidos: um endereço que redireciona conta como erro. Caso contrário, o ReceptionWorks tenta de novo: logo, depois após 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 12 horas. São 7 tentativas em cerca de 21 horas. Se todas falharem, o envio fica como Não entregue em «Registo de envios» e pode clicar em «Enviar novamente». As novas tentativas levam o mesmo webhook-id, pelo que o destino pode descartar duplicados.

Um destino é desativado automaticamente se responder que o endereço já não existe (código 410) ou se cinco eventos seguidos não forem entregues. A ficha mostra então «Desativado automaticamente» com o motivo e a sua equipa recebe uma notificação. Corrija o endereço e clique em «Ativar»: os eventos perdidos entretanto não são enviados.

Pausa, novo segredo, eliminação

Bom saber

O que fazer a seguir

← Todos os artigos