Webhooks pela API (e o que nasce com o cadastro)

POST /v1/webhooks

Os mesmos webhooks do painel, gerenciados com a sua chave de API em /v1/webhooks: criar (POST /v1/webhooks), listar (GET /v1/webhooks), ver um (GET /v1/webhooks/:id), alterar (PATCH /v1/webhooks/:id), apagar (DELETE /v1/webhooks/:id), testar (POST /v1/webhooks/:id/test, um evento assinado enviado na hora) e trocar o segredo (POST /v1/webhooks/:id/rotate-secret). Um webhook sem connectionId é da conta; com ele, recebe só os eventos desse número e substitui o da conta para esse número. O número é indicado pelo conn_… ou pelo seu externalId, e assim volta em cada resposta (com o externalId ao lado): nunca um id interno. O segredo de assinatura (whsec_…) e o token de cabeçalho, se você pediu com headerToken: true, aparecem uma única vez.

O webhook que nasce com o cadastro. Se você integra com links de cadastro, mande webhook: { url, events } em POST /v1/onboarding-links: validamos ao criar o link e devolvemos o segredo nesse momento. Quando o seu cliente termina, o número nasce com o seu webhook, assinado com ESSE segredo, e antes de connection.created: esse evento já chega nele. Depois você o encontra com GET /v1/webhooks?externalId=….

# 1) onboarding link + the webhook of the number it will connect
curl -X POST https://api.waiaconnect.com/v1/onboarding-links \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "pharmacy-42", "webhook": {"url": "https://api.yourcompany.com/hooks/connect", "events": ["connection.created", "message.received", "message.status"]}}'
# → { "url": "https://…/c/<token>", "publicId": "onb_…",
#     "webhook": { "secret": "whsec_…", "createdOnCompletion": true, … } }   ← store the secret NOW

# 2) after your customer connects: the number's webhooks, by your externalId
curl "https://api.waiaconnect.com/v1/webhooks?externalId=pharmacy-42" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "webhooks": [ { "id": "wh_…", "connectionId": "conn_…", "externalId": "pharmacy-42", … } ] }

# 3) create one directly (connectionId = conn_… or your externalId; omit = account-wide)
curl -X POST https://api.waiaconnect.com/v1/webhooks \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.yourcompany.com/hooks/connect-2", "connectionId": "pharmacy-42"}'

# rotate the secret (the old one stops verifying at once)
curl -X POST https://api.waiaconnect.com/v1/webhooks/wh_…/rotate-secret -H "Authorization: Bearer wc_live_YOUR_API_KEY"

const H = { "Authorization": "Bearer wc_live_YOUR_API_KEY", "Content-Type": "application/json" };

// 1) onboarding link + the webhook of the number it will connect
const link = await (await fetch("https://api.waiaconnect.com/v1/onboarding-links", {
  method: "POST", headers: H,
  body: JSON.stringify({
    externalId: "pharmacy-42",
    webhook: { url: "https://api.yourcompany.com/hooks/connect", events: ["connection.created", "message.received", "message.status"] }
  })
})).json();
await saveSecret("pharmacy-42", link.webhook.secret); // shown ONCE — it signs this number's events

// 2) later: the number's webhooks, by your externalId
const { webhooks } = await (await fetch("https://api.waiaconnect.com/v1/webhooks?externalId=pharmacy-42", { headers: H })).json();

// rotate the secret (the old one stops verifying at once)
const rotated = await (await fetch(`https://api.waiaconnect.com/v1/webhooks/${webhooks[0].id}/rotate-secret`, { method: "POST", headers: H })).json();
await saveSecret("pharmacy-42", rotated.secret);

<?php
function connect($method, $url, $body = null) {
  $ch = curl_init($url);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer wc_live_YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
  ]);
  return json_decode(curl_exec($ch), true);
}
// 1) onboarding link + the webhook of the number it will connect
$link = connect("POST", "https://api.waiaconnect.com/v1/onboarding-links", [
  "externalId" => "pharmacy-42",
  "webhook" => ["url" => "https://api.yourcompany.com/hooks/connect", "events" => ["connection.created", "message.received", "message.status"]],
]);
save_secret("pharmacy-42", $link["webhook"]["secret"]); // shown ONCE

// 2) later: the number's webhooks, by your externalId
$list = connect("GET", "https://api.waiaconnect.com/v1/webhooks?externalId=pharmacy-42");
// rotate the secret (the old one stops verifying at once)
$rotated = connect("POST", "https://api.waiaconnect.com/v1/webhooks/" . $list["webhooks"][0]["id"] . "/rotate-secret");

import requests
H = {"Authorization": "Bearer wc_live_YOUR_API_KEY"}

# 1) onboarding link + the webhook of the number it will connect
link = requests.post("https://api.waiaconnect.com/v1/onboarding-links", headers=H, json={
    "externalId": "pharmacy-42",
    "webhook": {"url": "https://api.yourcompany.com/hooks/connect",
                "events": ["connection.created", "message.received", "message.status"]},
}).json()
save_secret("pharmacy-42", link["webhook"]["secret"])  # shown ONCE

# 2) later: the number's webhooks, by your externalId
hooks = requests.get("https://api.waiaconnect.com/v1/webhooks", headers=H, params={"externalId": "pharmacy-42"}).json()["webhooks"]

# rotate the secret (the old one stops verifying at once)
rotated = requests.post(f"https://api.waiaconnect.com/v1/webhooks/{hooks[0]['id']}/rotate-secret", headers=H).json()

Limite: 2 webhooks por número (um ativo e outro para migrar sem corte), 2 × os seus números para todos os de número juntos, e 5 da conta; os desligados também contam. Passar dele ao criar ou ao mover um para um número → 422 WEBHOOK_LIMIT_REACHED com details.scope, used e limit. Os que você já tinha acima continuam funcionando: dá para editar, testar, trocar o segredo e apagar.

Filtros da lista: ?connectionId=conn_… (ou o seu externalId), ?connectionId=none (só os da conta) ou ?externalId= (vazia se esse número ainda não existe). Um wh_… ou um número de outra conta dá o mesmo 404 que um que não existe.

Reconectar o mesmo número com um link que traz a mesma URL não soma outro webhook: atualiza esse, com o segredo do link novo. Se o cadastro falhar, não fica nenhum webhook.

Trocar o segredo vale na hora: a partir daí assinamos com o novo e o antigo deixa de verificar. Atualize no seu sistema em seguida.