# Webhooks por API (y el que nace con el alta)

`POST /v1/webhooks`

Los mismos webhooks del panel, manejados con tu clave de API en `/v1/webhooks`: crear (`POST /v1/webhooks`), listar (`GET /v1/webhooks`), ver uno (`GET /v1/webhooks/:id`), cambiarlo (`PATCH /v1/webhooks/:id`), borrarlo (`DELETE /v1/webhooks/:id`), probarlo (`POST /v1/webhooks/:id/test`, un evento firmado que sale en el acto) y rotar su secreto (`POST /v1/webhooks/:id/rotate-secret`). Un webhook **sin** `connectionId` es de la cuenta; **con** él, recibe sólo los eventos de ese número y reemplaza al de la cuenta para ese número. El número se indica con su `conn_…` **o con tu `externalId`**, y así sale también en cada respuesta (con su `externalId` al lado): nunca un id interno. El secreto de firma (`whsec_…`) y el token de cabecera, si lo pediste con `headerToken: true`, salen **una sola vez**.

**El webhook que nace con el alta.** Si integrás con enlaces de alta, mandá `webhook: { url, events }` en `POST /v1/onboarding-links`: lo validamos al crear el enlace y el secreto te lo devolvemos **en ese momento**. Cuando tu cliente termina, el número nace con su webhook, firmado con ESE secreto, y antes de `connection.created`: ese evento ya te llega ahí. Después lo encontrás con `GET /v1/webhooks?externalId=…`.

## Ejemplos

### cURL

```bash
# 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"
```

### Node.js

```javascript
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

```php
<?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");
```

### Python

```python
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()
```

## Notas

- **Tope:** 2 webhooks por número (uno vivo y otro para migrar sin cortar), 2 × tus números para todos los de número juntos, y 5 de cuenta; cuentan los apagados también. Pasarlo al crear o al mover uno de número → `422 WEBHOOK_LIMIT_REACHED` con `details.scope`, `used` y `limit`. Los que ya tenías por encima siguen andando: los podés editar, probar, rotar y borrar.
- Filtros de la lista: `?connectionId=conn_…` (o tu `externalId`), `?connectionId=none` (sólo los de cuenta) o `?externalId=` (vacía si ese número todavía no existe). Un `wh_…` o un número de otra cuenta da el mismo 404 que uno que no existe.
- Reconectar el mismo número con un enlace que trae la misma URL no suma otro webhook: actualiza ése, con el secreto del enlace nuevo. Si el alta falla, no queda ningún webhook.
- Rotar el secreto vale en el acto: desde ese momento firmamos con el nuevo y el viejo deja de verificar. Actualizalo en tu sistema enseguida.