Webhooks

curl https://api.vitrinadev.com/api/v1/webhooks \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": [
    {
      "id": "d1d1d1d1-0000-4000-8000-000000000001",
      "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
      "url": "https://example.com/hooks/vitrina",
      "secret": "whsec_d1d…",
      "events": [
        "lead.created",
        "sla.breached"
      ],
      "enabled": true,
      "description": "ERP sync",
      "created_at": "2026-09-20T01:41:04.274Z",
      "updated_at": "2026-09-20T01:41:04.274Z",
      "last_delivery_at": "2026-09-20T01:42:12.154Z",
      "last_status": 200,
      "consecutive_failures": 0,
      "owner_kind": "api_key",
      "owner_id": "c1c1c1c1-0000-4000-8000-000000000001",
      "include_data": true,
      "paused_at": null,
      "paused_reason": null,
      "failing_since": null,
      "consecutive_failed_deliveries": 0
    }
  ]
}

curl -X POST https://api.vitrinadev.com/api/v1/webhooks \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/vitrina",
    "events": [
      "lead.created",
      "sla.breached"
    ],
    "description": "ERP sync"
  }'

{
  "data": {
    "id": "d1d1d1d1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "url": "https://example.com/hooks/vitrina",
    "secret": "whsec_d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1d1",
    "events": [
      "lead.created",
      "sla.breached"
    ],
    "enabled": true,
    "description": "ERP sync",
    "created_at": "2026-09-20T01:41:04.274Z",
    "updated_at": "2026-09-20T01:41:04.274Z",
    "last_delivery_at": null,
    "last_status": null,
    "consecutive_failures": 0,
    "owner_kind": "api_key",
    "owner_id": "c1c1c1c1-0000-4000-8000-000000000001",
    "include_data": false,
    "paused_at": null,
    "paused_reason": null,
    "failing_since": null,
    "consecutive_failed_deliveries": 0
  }
}

curl -X DELETE https://api.vitrinadev.com/api/v1/webhooks/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

curl https://api.vitrinadev.com/api/v1/webhooks/<id> \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "id": "d1d1d1d1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "url": "https://example.com/hooks/vitrina",
    "secret": "whsec_d1d…",
    "events": [
      "lead.created",
      "sla.breached"
    ],
    "enabled": true,
    "description": "ERP sync",
    "created_at": "2026-09-20T01:41:04.274Z",
    "updated_at": "2026-09-20T01:41:04.274Z",
    "last_delivery_at": null,
    "last_status": null,
    "consecutive_failures": 0,
    "owner_kind": "api_key",
    "owner_id": "c1c1c1c1-0000-4000-8000-000000000001",
    "include_data": false,
    "paused_at": null,
    "paused_reason": null,
    "failing_since": null,
    "consecutive_failed_deliveries": 0
  }
}

curl -X PUT https://api.vitrinadev.com/api/v1/webhooks/<id> \
  -H "Authorization: Bearer $VITRINA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

{
  "data": {
    "id": "d1d1d1d1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "url": "https://example.com/hooks/vitrina",
    "secret": "whsec_d1d…",
    "events": [
      "lead.created",
      "sla.breached"
    ],
    "enabled": false,
    "description": "ERP sync",
    "created_at": "2026-09-20T01:41:04.274Z",
    "updated_at": "2026-09-20T01:41:04.274Z",
    "last_delivery_at": null,
    "last_status": null,
    "consecutive_failures": 0,
    "owner_kind": "api_key",
    "owner_id": "c1c1c1c1-0000-4000-8000-000000000001",
    "include_data": false,
    "paused_at": null,
    "paused_reason": null,
    "failing_since": null,
    "consecutive_failed_deliveries": 0
  }
}

curl https://api.vitrinadev.com/api/v1/webhooks/<id>/deliveries \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": [
    {
      "id": 54,
      "subscription_id": "d1d1d1d1-0000-4000-8000-000000000001",
      "event": "lead.created",
      "event_id": "99999999-0000-4000-8000-000000000001",
      "attempt": 1,
      "status_code": 200,
      "error": null,
      "response_excerpt": "{\"ok\":true}",
      "request_payload": {
        "id": "99999999-0000-4000-8000-000000000001",
        "type": "lead.created",
        "version": 1,
        "created_at": "2026-09-20T01:42:11.194Z",
        "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
        "resource": {
          "type": "lead",
          "id": "99999999-0000-4000-8000-000000000002",
          "url": "https://api.vitrinadev.com/api/v1/leads/99999999-0000-4000-8000-000000000002"
        },
        "author": {
          "kind": "api_key",
          "id": "c1c1c1c1-0000-4000-8000-000000000001",
          "name": "Website integration"
        },
        "data": {
          "lead_id": "99999999-0000-4000-8000-000000000002",
          "contact_id": "22222222-0000-4000-8000-000000000001",
          "pipeline_id": "44444444-0000-4000-8000-000000000001",
          "stage_id": "55555555-0000-4000-8000-000000000001",
          "title": "Lead disparado desde el sitio",
          "intent": "buy",
          "source": "website",
          "value_amount": null,
          "value_currency": "CLP",
          "owner_user_id": null,
          "team_id": null
        }
      },
      "latency_ms": 549,
      "created_at": "2026-09-20T01:42:12.116Z",
      "redelivery_of": null
    }
  ],
  "meta": {
    "pagination": {
      "limit": 50
    },
    "offset": 0
  }
}

curl -X POST https://api.vitrinadev.com/api/v1/webhooks/<id>/deliveries/<id>/redeliver \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "subscription_id": "d1d1d1d1-0000-4000-8000-000000000001",
    "delivery_id": 54,
    "event": "lead.created",
    "event_id": "99999999-0000-4000-8000-000000000001",
    "status": "queued"
  }
}

curl -X POST https://api.vitrinadev.com/api/v1/webhooks/<id>/resume \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "id": "d1d1d1d1-0000-4000-8000-000000000001",
    "tenant_id": "a1a1a1a1-0000-4000-8000-000000000001",
    "url": "https://example.com/hooks/vitrina",
    "secret": "whsec_d1d…",
    "events": [
      "lead.created",
      "sla.breached"
    ],
    "enabled": true,
    "description": "ERP sync",
    "created_at": "2026-09-20T01:41:04.274Z",
    "updated_at": "2026-09-20T01:41:04.274Z",
    "last_delivery_at": null,
    "last_status": null,
    "consecutive_failures": 0,
    "owner_kind": "api_key",
    "owner_id": "c1c1c1c1-0000-4000-8000-000000000001",
    "include_data": false,
    "paused_at": null,
    "paused_reason": null,
    "failing_since": null,
    "consecutive_failed_deliveries": 0
  }
}

curl https://api.vitrinadev.com/api/v1/webhooks/events \
  -H "Authorization: Bearer $VITRINA_KEY"

{
  "data": {
    "events": [
      {
        "name": "sending_domain.verified",
        "version": 1,
        "resource_type": "sending_domain",
        "read_scope": "messaging_accounts:read",
        "sensitive": false,
        "description": "A tenant email sending domain finished DKIM verification and can now send email campaigns (ADR 0032).",
        "fires_when": "A sending-domain refresh observes SES flip VerifiedForSendingStatus to true for the first time.",
        "data_schema": {
          "id (string, uuid)": "The verified sending domain",
          "domain (string)": "The domain name"
        },
        "sample": {
          "id": "99999999-0000-4000-8000-000000000005",
          "domain": "mail.cliente.cl"
        }
      }
    ],
    "signing": {
      "envelope": {
        "id (string, uuid)": "Unique event id; use for idempotency",
        "type (string)": "One of the events above",
        "version (integer)": "The schema version of this event type; bumped only on a breaking change to `data`",
        "livemode (boolean)": "`false` when the event came from a sandbox (test-mode) workspace, `true` otherwise. Mirrored on the `Vitrina-Livemode` header.",
        "created_at (string, ISO 8601 timestamp)": "When the event was produced",
        "tenant_id (string, uuid)": "Your workspace id",
        "resource (object)": "{ type, id, url } — what the event is about; GET `url` with your credential to read it",
        "changes (object, optional)": "field → { from, to } for the identifiers and states that changed",
        "author (object)": "{ kind: 'member' | 'api_key' | 'ai_agent' | 'system' | 'contact', id, name, via? } — who did it",
        "data (object, optional)": "The resource payload (see catalog); present only when the subscription includes data and its owner may read it",
        "data_omitted (string, optional)": "Why `data` is not in this delivery; exactly one of `data` / `data_omitted` is present"
      },
      "data_modes": {
        "notice": "The default. Every delivery carries the notice — resource, changes, author, time, url — and `data_omitted: \"not_requested\"`.",
        "data": "«Incluir datos del recurso» (`include_data: true`). `data` is added when, at dispatch time, the subscription owner holds the resource read scope and sees every record; otherwise the delivery is a notice with the reason in `data_omitted`.",
        "not_requested": "The subscription did not ask for data.",
        "sensitive": "The event is about a dato sensible (health data). It is always a notice, whatever the subscription asked for.",
        "missing_scope:<scope>": "The owner does not hold that read scope (e.g. `missing_scope:contacts:read`).",
        "restricted_visibility": "The owner sees only some records (assigned-only, or some sucursales).",
        "owner_unavailable": "The owner is no longer an active member, or its API key was revoked or expired. Recreate the subscription, or edit its URL or events, to make yourself its owner."
      },
      "headers": {
        "X-Webhook-Event": "The event name (e.g. lead.created).",
        "X-Webhook-Event-Id": "Unique event id. Retries reuse this id so you can dedupe.",
        "X-Webhook-Timestamp": "Unix seconds when the signature was generated.",
        "X-Webhook-Signature": "t=<unix>,v1=<hex> — HMAC-SHA256 of `${timestamp}.${rawBody}` with your subscription secret.",
        "Vitrina-Livemode": "`true` or `false`, mirroring the body's `livemode`. Signed as part of the body — verifying the signature verifies this too."
      },
      "signature_scheme": "hmac-sha256",
      "signature_format": "t=<unix>,v1=<hex>",
      "verify_pseudocode": [
        "const [ts, sig] = parseHeader('X-Webhook-Signature');  // 't=…,v1=…'",
        "const expected = hmac_sha256(secret, ts + '.' + rawBody);  // hex",
        "if (!timing_safe_equal(sig.v1, expected)) reject(401);",
        "if (Math.abs(now_unix() - ts) > 300) reject(401);  // 5-min replay window"
      ],
      "timing_window_seconds": 300,
      "retry": {
        "attempts": 5,
        "backoff": "exponential",
        "delays_seconds": [
          5,
          10,
          20,
          40,
          80
        ],
        "note": "All retries reuse the same X-Webhook-Event-Id so your endpoint can be idempotent."
      },
      "auto_pause": {
        "consecutive_failed_deliveries": 20,
        "failing_hours": 24,
        "note": "A subscription is paused when 20 events in a row exhaust their retries, or when it has failed for 24 hours without a single success. The workspace admins are notified once. A paused subscription receives nothing until POST /webhooks/{id}/resume; events in between are not queued — read the resources to catch up, or redeliver from the delivery log."
      }
    }
  }
}