# Zapier, Make e n8n

Use os eventos do ByDomu como gatilho e a API como ação, com uma chave secreta.

Guia Com aprovação Chave secreta

**Antes de começar.** Você precisa de uma chave secreta com webhooks:write para criar a assinatura (o suporte aprova: peça em Configurações › API Keys) e, se a automação escreve no ByDomu, a permissão :write do que ela tocar. Ler o catálogo (events:read) vem com as secretas de leitura.

## Crie o gatilho e copie a URL

As três plataformas recebem webhooks com um passo que dá uma URL pública. Essa URL é a que o ByDomu vai chamar a cada evento.

Plataforma Passo

Zapier `Webhooks by Zapier › Catch Hook`

Make `Webhooks › Custom webhook`

n8n `Nó Webhook (POST)`

## Assine essa URL aos eventos

`GET /events` lista o catálogo com uma descrição e um exemplo por evento. Assine tipos exatos (deal.won), um objeto (contact.*) ou todos (*). A URL precisa ser pública: as privadas ou internas são recusadas.

```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"
  }'
```

Você também pode criá-la, testá-la e rotacionar o segredo na aba Webhooks de Configurações › API Keys. Para a plataforma aprender os campos antes do primeiro evento real, peça uma amostra e envie para a 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).
```

## Mapeie os campos

Tudo vem em data, um objeto por ficha: data.deal.title, data.contact.firstName, data.transition.toStageName. Use type para filtrar e id para não processar duas vezes a mesma 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
    }
  }
}
```

## Escreva no ByDomu como ação

Para criar ou mudar coisas no ByDomu a partir de outra ferramenta, use o passo HTTP de cada plataforma com X-API-Key e uma Idempotency-Key montada com ids da execução: se a plataforma repetir, nada se duplica.

Plataforma Passo

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"] }
```

## Se algo falhar

- **403** Falta à chave webhooks:write (ou o :write da ação). Peça em Configurações › API Keys.
- **400** A URL não é pública ou um tipo não existe no catálogo.
- **x2** Chegou duas vezes: é uma nova tentativa. Descarte pelo id.
- **sig** Zapier e Make não verificam a assinatura sozinhos: trate a URL do gatilho como um segredo. Se puder, verifique num passo de código.

[Como verificar a assinatura](https://developers.bydomu.com/pt/guias/firma-webhooks)