# Zapier, Make y n8n

Usa los eventos de ByDomu como disparador y la API como acción, con una clave secreta.

Guía Con aprobación Clave secreta

**Antes de empezar.** Necesitas una clave secreta con webhooks:write para crear la suscripción (lo aprueba soporte: pídelo en Configuración › API Keys) y, si la automatización escribe en ByDomu, el permiso :write de lo que toque. Leer el catálogo (events:read) viene con las secretas de lectura.

## Crea el disparador y copia su URL

Las tres plataformas reciben webhooks con un paso que te da una URL pública. Esa URL es la que ByDomu va a llamar en cada evento.

Plataforma Paso

Zapier `Webhooks by Zapier › Catch Hook`

Make `Webhooks › Custom webhook`

n8n `Nodo Webhook (POST)`

## Suscribe esa URL a los eventos

`GET /events` lista el catálogo con una descripción y un ejemplo por evento. Suscríbete a tipos exactos (deal.won), a un objeto (contact.*) o a todos (*). La URL tiene que ser pública: se rechazan las privadas o internas.

```bash
curl -X POST https://api.bydomu.com/v1/webhooks \
  -H "X-API-Key: $BYDOMU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.zapier.com/hooks/catch/000000/xxxxxx/",
    "eventTypes": ["deal.won"],
    "description": "Zap: negocios ganados a Google Sheets"
  }'
```

También puedes crearla, probarla y rotar su secreto en la pestaña Webhooks de Configuración › API Keys. Para que la plataforma aprenda los campos antes del primer evento real, pide una muestra y mándala a la URL:

```bash
curl https://api.bydomu.com/v1/webhooks/sample/deal.won -H "X-API-Key: $BYDOMU_API_KEY"
# El último deal.won real de tu cuenta (meta.synthetic: false) o, si no hay,
# el árbol de campos con valores null (meta.synthetic: true).
```

## Mapea los campos

Todo viene en data, un objeto por ficha: data.deal.title, data.contact.firstName, data.transition.toStageName. Usa type para filtrar y id para no procesar dos veces la misma entrega.

**Entrega · deal.won**

```json
{
  "event": "deal.won",
  "id": "5f3a0c1e-7d2b-4f7e-9a51-0b6c1d2e3f40",
  "type": "deal.won",
  "timestamp": "2026-09-22T14:30:00.000Z",
  "organizationId": "clx1org001",
  "actor": {
    "kind": "USER",
    "userId": "clx1usr001"
  },
  "data": {
    "deal": {
      "id": "clx1deal001",
      "code": "N-0042",
      "title": "Compra apartamento Chapinero · Laura Restrepo",
      "value": 450000000,
      "currency": "COP",
      "probability": 100,
      "status": "WON",
      "intent": "PURCHASE",
      "leadSource": "PORTAL",
      "lostReason": null,
      "aiCreated": false,
      "agentId": "clx1usr001",
      "contactId": "clx1con001",
      "pipelineId": "clx1pip001",
      "stageId": "clx1stg005",
      "stageName": "Ganado",
      "stageEnteredAt": "2026-09-22T14:30:00.000Z",
      "expectedCloseDate": "2026-10-31T00:00:00.000Z",
      "closedAt": "2026-09-22T14:30:00.000Z",
      "createdAt": "2026-09-20T15:05:00.000Z",
      "saasPlanId": null,
      "saasPlanName": null,
      "saasBillingPeriod": null,
      "saasMrrAmount": null,
      "trialStartedAt": null,
      "trialEndsAt": null
    },
    "contact": {
      "id": "clx1con001",
      "code": "C-0042",
      "firstName": "Laura",
      "lastName": "Restrepo",
      "fullName": "Laura Restrepo",
      "email": "laura.restrepo@example.com",
      "phone": "+573000000001",
      "source": "WEBSITE",
      "status": "QUALIFIED",
      "type": "CLIENT",
      "score": 72,
      "ownerId": "clx1usr001",
      "preferredCity": "Bogotá",
      "preferredType": "APARTMENT",
      "budget": 450000000,
      "currency": "COP",
      "tags": [
        "Compra",
        "Chapinero"
      ],
      "createdAt": "2026-09-20T15:04:00.000Z"
    },
    "transition": {
      "fromStageId": "clx1stg003",
      "fromStageName": "Negociación",
      "toStageId": "clx1stg005",
      "toStageName": "Ganado",
      "pipelineId": "clx1pip001",
      "lostReason": null,
      "automated": false
    }
  }
}
```

## Escribe en ByDomu como acción

Para crear o cambiar cosas en ByDomu desde otra herramienta, usa el paso HTTP de cada plataforma con X-API-Key y una Idempotency-Key armada con ids de la ejecución: si la plataforma reintenta, no se duplica.

Plataforma Paso

Zapier `Webhooks by Zapier › Custom Request`

Make `HTTP › Make a request`

n8n `HTTP Request`

```
POST https://api.bydomu.com/v1/contacts
X-API-Key: domu_sk_live_…           (con contacts:write, aprobado por soporte)
Content-Type: application/json
Idempotency-Key: zap-{{zap_meta_id}}-{{row_id}}

{ "firstName": "{{nombre}}", "phone": "{{telefono}}", "source": "WEBSITE", "tags": ["Zapier"] }
```

## Si algo falla

- **403** A la clave le falta webhooks:write (o el :write de la acción). Pídelo en Configuración › API Keys.
- **400** La URL no es pública o un tipo no existe en el catálogo.
- **x2** Llegó dos veces: es un reintento. Descártalo por id.
- **sig** Zapier y Make no verifican la firma solos: trata la URL del disparador como un secreto. Si puedes, verifícala en un paso de código.

[Cómo verificar la firma](https://developers.bydomu.com/guias/firma-webhooks)