ByDomuDevelopers
Create key

Zapier, Make and n8n

Use ByDomu events as a trigger and the API as an action, with a secret key.

GuideWith approvalSecret key
Before you start. You need a secret key with webhooks:write to create the subscription (support approves it: request it in Settings › API Keys) and, if the automation writes to ByDomu, the :write permission for what it touches. Reading the catalog (events:read) comes with read-only secret keys.

Create the trigger and copy its URL

All three platforms receive webhooks with a step that gives you a public URL. That URL is what ByDomu will call on each event.

PlatformStep
ZapierWebhooks by Zapier › Catch Hook
MakeWebhooks › Custom webhook
n8nWebhook node (POST)

Subscribe that URL to the events

GET /events lists the catalog with a description and an example per event. Subscribe to exact types (deal.won), a whole object (contact.*) or everything (*). The URL must be public: private or internal ones are rejected.

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

You can also create it, test it and rotate its secret in the Webhooks tab of Settings › API Keys. So the platform learns the fields before the first real event, fetch a sample and send it to the URL:

cURL
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).

Map the fields

Everything comes in data, one object per record: data.deal.title, data.contact.firstName, data.transition.toStageName. Use type to filter and id to avoid processing the same delivery twice.

Delivery · deal.won
{
  "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": "[email protected]",
      "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
    }
  }
}

Write to ByDomu as an action

To create or change things in ByDomu from another tool, use each platform’s HTTP step with X-API-Key and an Idempotency-Key built from run ids: if the platform retries, nothing is duplicated.

PlatformStep
ZapierWebhooks by Zapier › Custom Request
MakeHTTP › Make a request
n8nHTTP Request
HTTP
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"] }

If something fails

  • 403The key lacks webhooks:write (or the action’s :write). Request it in Settings › API Keys.
  • 400The URL isn’t public or a type isn’t in the catalog.
  • x2It arrived twice: it’s a retry. Drop it by id.
  • sigZapier and Make don’t verify the signature on their own: treat the trigger URL as a secret. If you can, verify it in a code step.

How to verify the signature