{
  "openapi": "3.1.0",
  "info": {
    "title": "HolidayOS Connect API",
    "version": "1.0",
    "description": "Submit enquiries from your website or partner systems into HolidayOS, and receive customer-safe lifecycle events back over signed webhooks.",
    "contact": {
      "name": "HolidayOS",
      "url": "https://holidayos.ai/developers/connect",
      "email": "hello@holidayos.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.new.holidayos.ai",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ConnectKey": [],
      "ConnectTenant": [],
      "ConnectSignature": []
    }
  ],
  "paths": {
    "/api/v1/crm/connect/events": {
      "post": {
        "tags": [
          "Connect"
        ],
        "summary": "Ingest a batch of Connect events",
        "description": "Accepts 1–100 event envelopes. Requires the `events:ingest` scope. Validation is all-or-nothing: a single bad envelope rejects the batch and writes nothing.",
        "operationId": "ingestConnectEvents",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "events"
                ],
                "properties": {
                  "events": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "specVersion",
                        "eventId",
                        "eventType",
                        "occurredAt",
                        "tenant",
                        "origin",
                        "actor"
                      ],
                      "properties": {
                        "specVersion": {
                          "type": "string",
                          "maxLength": 16,
                          "example": "1.0"
                        },
                        "eventId": {
                          "type": "string",
                          "maxLength": 100,
                          "description": "Globally unique. The idempotency key — reuse it on retry."
                        },
                        "eventType": {
                          "type": "string",
                          "enum": [
                            "contact.identified",
                            "contact.updated",
                            "enquiry.submitted",
                            "trip.planning_started",
                            "trip.draft_updated",
                            "quote.requested",
                            "booking.started",
                            "booking.abandoned",
                            "booking.completed"
                          ]
                        },
                        "occurredAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "ISO-8601 instant the event occurred on the source system."
                        },
                        "tenant": {
                          "type": "string",
                          "maxLength": 100,
                          "description": "Must match the tenant bound to the API key.",
                          "example": "your-tenant-slug"
                        },
                        "origin": {
                          "type": "string",
                          "maxLength": 100,
                          "description": "Emitting system, used for loop prevention on the two-way channel."
                        },
                        "actor": {
                          "type": "object",
                          "required": [
                            "type"
                          ],
                          "description": "The traveller the event is about. At least one of email, phone, or externalId is required.",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "contact"
                              ]
                            },
                            "email": {
                              "type": "string",
                              "format": "email",
                              "maxLength": 320
                            },
                            "externalId": {
                              "type": "string",
                              "maxLength": 200
                            },
                            "name": {
                              "type": "string",
                              "maxLength": 200
                            },
                            "phone": {
                              "type": "string",
                              "maxLength": 40
                            }
                          },
                          "anyOf": [
                            {
                              "required": [
                                "email"
                              ]
                            },
                            {
                              "required": [
                                "phone"
                              ]
                            },
                            {
                              "required": [
                                "externalId"
                              ]
                            }
                          ]
                        },
                        "payload": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Event-specific body. Intentionally open for the public spec."
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "events": [
                  {
                    "specVersion": "1.0",
                    "eventId": "source_event_id",
                    "eventType": "enquiry.submitted",
                    "occurredAt": "2026-08-23T09:15:00Z",
                    "tenant": "your-tenant-slug",
                    "origin": "source-system",
                    "actor": {
                      "type": "contact",
                      "email": "traveler@example.com",
                      "name": "Ana Silva",
                      "phone": "+60123456789"
                    },
                    "payload": {
                      "destination": "Bali",
                      "travelDates": {
                        "startDate": "2026-11-04",
                        "endDate": "2026-11-10"
                      },
                      "party": {
                        "adults": 3,
                        "children": 0,
                        "rooms": 1
                      },
                      "message": "Customer requested advisor pricing before checkout.",
                      "quote": {
                        "status": "pending",
                        "currency": "USD"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch processed. Inspect `results` for the per-event outcome.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "accepted",
                    "duplicate",
                    "failed",
                    "results"
                  ],
                  "properties": {
                    "accepted": {
                      "type": "integer"
                    },
                    "duplicate": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "eventId",
                          "status"
                        ],
                        "properties": {
                          "eventId": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "accepted",
                              "duplicate",
                              "failed"
                            ]
                          },
                          "error": {
                            "type": "string",
                            "description": "Present only on `failed`. A safe, non-leaking reason."
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "accepted": 1,
                  "duplicate": 0,
                  "failed": 0,
                  "results": [
                    {
                      "eventId": "source_event_id",
                      "status": "accepted"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The batch was rejected before anything was written. An envelope failed validation (missing field, unknown `eventType`, malformed `occurredAt`). `actor` carries none of `email`, `phone`, or `externalId` — there is no key to dedupe on. The envelope `tenant` does not match the authenticated key's tenant. More than 100 events, or an empty `events` array. Fix the payload. Retrying the same body will fail identically."
          },
          "401": {
            "description": "`Invalid Connect credentials` — one generic message for every auth failure. `X-Connect-Key`, `X-Connect-Signature`, or `X-Connect-Tenant` missing or malformed. The key prefix is unknown, revoked, or expired. The signature does not verify — usually because the signed bytes are not the bytes sent. The timestamp is outside the ±5 minute window (check server clock drift). The exact same signature was already used inside the freshness window (replay). Re-sign with a fresh timestamp. If it still fails, verify you sign the raw body bytes you actually transmit."
          },
          "403": {
            "description": "Authenticated, but not authorised. The key does not hold the `events:ingest` scope. `X-Connect-Tenant` does not match the tenant bound to the key. Fix the key's scopes or the tenant header. Retrying unchanged will fail."
          },
          "503": {
            "description": "Replay protection is temporarily unavailable. The replay guard store could not be reached. Safe to retry shortly with the same `eventId` values — nothing was ingested."
          }
        }
      }
    }
  },
  "webhooks": {
    "lead.assigned": {
      "post": {
        "summary": "An advisor was assigned, or reassigned, to an enquiry.",
        "operationId": "webhook_lead_assigned",
        "parameters": [
          {
            "name": "X-Connect-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1787654321,v1=<hex>"
            },
            "description": "HMAC-SHA256 of `<t>.<raw body>` keyed by the subscription secret."
          },
          {
            "name": "X-Connect-Tenant",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-tenant-slug"
            }
          },
          {
            "name": "X-Connect-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "lead.assigned"
            }
          },
          {
            "name": "X-Connect-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Delivery row id. Stable across retries of the same delivery."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "specVersion",
                  "eventId",
                  "eventType",
                  "occurredAt",
                  "tenant",
                  "origin",
                  "actor",
                  "payload"
                ],
                "properties": {
                  "specVersion": {
                    "type": "string",
                    "example": "1.0"
                  },
                  "eventId": {
                    "type": "string",
                    "description": "UUID. Stable across retries — dedupe on it."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "lead.assigned",
                      "lead.stage_changed",
                      "proposal.sent",
                      "proposal.ready",
                      "proposal.viewed",
                      "message.posted"
                    ]
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "tenant": {
                    "type": "string",
                    "example": "your-tenant-slug"
                  },
                  "origin": {
                    "type": "string",
                    "example": "crm"
                  },
                  "actor": {
                    "type": "object",
                    "required": [
                      "type"
                    ],
                    "description": "The traveller the event is about. At least one of email, phone, or externalId is required.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "contact"
                        ]
                      },
                      "email": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 320
                      },
                      "externalId": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "name": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "phone": {
                        "type": "string",
                        "maxLength": 40
                      }
                    },
                    "anyOf": [
                      {
                        "required": [
                          "email"
                        ]
                      },
                      {
                        "required": [
                          "phone"
                        ]
                      },
                      {
                        "required": [
                          "externalId"
                        ]
                      }
                    ]
                  },
                  "payload": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              },
              "example": {
                "specVersion": "1.0",
                "eventId": "5f1c0000-0000-4000-8000-000000000000",
                "eventType": "lead.assigned",
                "occurredAt": "2026-08-23T09:15:00Z",
                "tenant": "your-tenant-slug",
                "origin": "crm",
                "actor": {
                  "type": "contact",
                  "email": "traveler@example.com",
                  "name": "Ana Silva"
                },
                "payload": {
                  "leadId": "lead_01H…",
                  "owner": "advisor@agency.com",
                  "title": "Ana Silva — Bali"
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Return within 10s or the delivery is retried."
          }
        }
      }
    },
    "lead.stage_changed": {
      "post": {
        "summary": "An enquiry moved between pipeline stages.",
        "operationId": "webhook_lead_stage_changed",
        "parameters": [
          {
            "name": "X-Connect-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1787654321,v1=<hex>"
            },
            "description": "HMAC-SHA256 of `<t>.<raw body>` keyed by the subscription secret."
          },
          {
            "name": "X-Connect-Tenant",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-tenant-slug"
            }
          },
          {
            "name": "X-Connect-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "lead.stage_changed"
            }
          },
          {
            "name": "X-Connect-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Delivery row id. Stable across retries of the same delivery."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "specVersion",
                  "eventId",
                  "eventType",
                  "occurredAt",
                  "tenant",
                  "origin",
                  "actor",
                  "payload"
                ],
                "properties": {
                  "specVersion": {
                    "type": "string",
                    "example": "1.0"
                  },
                  "eventId": {
                    "type": "string",
                    "description": "UUID. Stable across retries — dedupe on it."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "lead.assigned",
                      "lead.stage_changed",
                      "proposal.sent",
                      "proposal.ready",
                      "proposal.viewed",
                      "message.posted"
                    ]
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "tenant": {
                    "type": "string",
                    "example": "your-tenant-slug"
                  },
                  "origin": {
                    "type": "string",
                    "example": "crm"
                  },
                  "actor": {
                    "type": "object",
                    "required": [
                      "type"
                    ],
                    "description": "The traveller the event is about. At least one of email, phone, or externalId is required.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "contact"
                        ]
                      },
                      "email": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 320
                      },
                      "externalId": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "name": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "phone": {
                        "type": "string",
                        "maxLength": 40
                      }
                    },
                    "anyOf": [
                      {
                        "required": [
                          "email"
                        ]
                      },
                      {
                        "required": [
                          "phone"
                        ]
                      },
                      {
                        "required": [
                          "externalId"
                        ]
                      }
                    ]
                  },
                  "payload": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              },
              "example": {
                "specVersion": "1.0",
                "eventId": "5f1c0000-0000-4000-8000-000000000000",
                "eventType": "lead.stage_changed",
                "occurredAt": "2026-08-23T09:15:00Z",
                "tenant": "your-tenant-slug",
                "origin": "crm",
                "actor": {
                  "type": "contact",
                  "email": "traveler@example.com",
                  "name": "Ana Silva"
                },
                "payload": {
                  "leadId": "lead_01H…",
                  "fromStage": "inquiry",
                  "toStage": "proposal_sent",
                  "title": "Ana Silva — Bali"
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Return within 10s or the delivery is retried."
          }
        }
      }
    },
    "proposal.sent": {
      "post": {
        "summary": "A proposal was sent to the traveller. Carries the hosted proposal link.",
        "operationId": "webhook_proposal_sent",
        "parameters": [
          {
            "name": "X-Connect-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1787654321,v1=<hex>"
            },
            "description": "HMAC-SHA256 of `<t>.<raw body>` keyed by the subscription secret."
          },
          {
            "name": "X-Connect-Tenant",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-tenant-slug"
            }
          },
          {
            "name": "X-Connect-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "proposal.sent"
            }
          },
          {
            "name": "X-Connect-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Delivery row id. Stable across retries of the same delivery."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "specVersion",
                  "eventId",
                  "eventType",
                  "occurredAt",
                  "tenant",
                  "origin",
                  "actor",
                  "payload"
                ],
                "properties": {
                  "specVersion": {
                    "type": "string",
                    "example": "1.0"
                  },
                  "eventId": {
                    "type": "string",
                    "description": "UUID. Stable across retries — dedupe on it."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "lead.assigned",
                      "lead.stage_changed",
                      "proposal.sent",
                      "proposal.ready",
                      "proposal.viewed",
                      "message.posted"
                    ]
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "tenant": {
                    "type": "string",
                    "example": "your-tenant-slug"
                  },
                  "origin": {
                    "type": "string",
                    "example": "crm"
                  },
                  "actor": {
                    "type": "object",
                    "required": [
                      "type"
                    ],
                    "description": "The traveller the event is about. At least one of email, phone, or externalId is required.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "contact"
                        ]
                      },
                      "email": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 320
                      },
                      "externalId": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "name": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "phone": {
                        "type": "string",
                        "maxLength": 40
                      }
                    },
                    "anyOf": [
                      {
                        "required": [
                          "email"
                        ]
                      },
                      {
                        "required": [
                          "phone"
                        ]
                      },
                      {
                        "required": [
                          "externalId"
                        ]
                      }
                    ]
                  },
                  "payload": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              },
              "example": {
                "specVersion": "1.0",
                "eventId": "5f1c0000-0000-4000-8000-000000000000",
                "eventType": "proposal.sent",
                "occurredAt": "2026-08-23T09:15:00Z",
                "tenant": "your-tenant-slug",
                "origin": "crm",
                "actor": {
                  "type": "contact",
                  "email": "traveler@example.com",
                  "name": "Ana Silva"
                },
                "payload": {
                  "proposalId": "prop_01H…",
                  "tripId": "trip_01H…",
                  "title": "Bali — 6 nights",
                  "proposalUrl": "https://app.holidayos.ai/p/…",
                  "channel": "email"
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Return within 10s or the delivery is retried."
          }
        }
      }
    },
    "proposal.ready": {
      "post": {
        "summary": "Reserved in the allowlist. No code path emits it yet — do not wait on it.",
        "description": "Reserved in the allowlist; no code path emits this event yet.",
        "operationId": "webhook_proposal_ready",
        "parameters": [
          {
            "name": "X-Connect-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1787654321,v1=<hex>"
            },
            "description": "HMAC-SHA256 of `<t>.<raw body>` keyed by the subscription secret."
          },
          {
            "name": "X-Connect-Tenant",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-tenant-slug"
            }
          },
          {
            "name": "X-Connect-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "proposal.ready"
            }
          },
          {
            "name": "X-Connect-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Delivery row id. Stable across retries of the same delivery."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "specVersion",
                  "eventId",
                  "eventType",
                  "occurredAt",
                  "tenant",
                  "origin",
                  "actor",
                  "payload"
                ],
                "properties": {
                  "specVersion": {
                    "type": "string",
                    "example": "1.0"
                  },
                  "eventId": {
                    "type": "string",
                    "description": "UUID. Stable across retries — dedupe on it."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "lead.assigned",
                      "lead.stage_changed",
                      "proposal.sent",
                      "proposal.ready",
                      "proposal.viewed",
                      "message.posted"
                    ]
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "tenant": {
                    "type": "string",
                    "example": "your-tenant-slug"
                  },
                  "origin": {
                    "type": "string",
                    "example": "crm"
                  },
                  "actor": {
                    "type": "object",
                    "required": [
                      "type"
                    ],
                    "description": "The traveller the event is about. At least one of email, phone, or externalId is required.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "contact"
                        ]
                      },
                      "email": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 320
                      },
                      "externalId": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "name": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "phone": {
                        "type": "string",
                        "maxLength": 40
                      }
                    },
                    "anyOf": [
                      {
                        "required": [
                          "email"
                        ]
                      },
                      {
                        "required": [
                          "phone"
                        ]
                      },
                      {
                        "required": [
                          "externalId"
                        ]
                      }
                    ]
                  },
                  "payload": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              },
              "example": {
                "specVersion": "1.0",
                "eventId": "5f1c0000-0000-4000-8000-000000000000",
                "eventType": "proposal.ready",
                "occurredAt": "2026-08-23T09:15:00Z",
                "tenant": "your-tenant-slug",
                "origin": "crm",
                "actor": {
                  "type": "contact",
                  "email": "traveler@example.com",
                  "name": "Ana Silva"
                },
                "payload": {
                  "proposalId": "prop_01H…",
                  "tripId": "trip_01H…"
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Return within 10s or the delivery is retried."
          }
        }
      }
    },
    "proposal.viewed": {
      "post": {
        "summary": "The traveller opened the hosted proposal.",
        "operationId": "webhook_proposal_viewed",
        "parameters": [
          {
            "name": "X-Connect-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1787654321,v1=<hex>"
            },
            "description": "HMAC-SHA256 of `<t>.<raw body>` keyed by the subscription secret."
          },
          {
            "name": "X-Connect-Tenant",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-tenant-slug"
            }
          },
          {
            "name": "X-Connect-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "proposal.viewed"
            }
          },
          {
            "name": "X-Connect-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Delivery row id. Stable across retries of the same delivery."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "specVersion",
                  "eventId",
                  "eventType",
                  "occurredAt",
                  "tenant",
                  "origin",
                  "actor",
                  "payload"
                ],
                "properties": {
                  "specVersion": {
                    "type": "string",
                    "example": "1.0"
                  },
                  "eventId": {
                    "type": "string",
                    "description": "UUID. Stable across retries — dedupe on it."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "lead.assigned",
                      "lead.stage_changed",
                      "proposal.sent",
                      "proposal.ready",
                      "proposal.viewed",
                      "message.posted"
                    ]
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "tenant": {
                    "type": "string",
                    "example": "your-tenant-slug"
                  },
                  "origin": {
                    "type": "string",
                    "example": "crm"
                  },
                  "actor": {
                    "type": "object",
                    "required": [
                      "type"
                    ],
                    "description": "The traveller the event is about. At least one of email, phone, or externalId is required.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "contact"
                        ]
                      },
                      "email": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 320
                      },
                      "externalId": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "name": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "phone": {
                        "type": "string",
                        "maxLength": 40
                      }
                    },
                    "anyOf": [
                      {
                        "required": [
                          "email"
                        ]
                      },
                      {
                        "required": [
                          "phone"
                        ]
                      },
                      {
                        "required": [
                          "externalId"
                        ]
                      }
                    ]
                  },
                  "payload": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              },
              "example": {
                "specVersion": "1.0",
                "eventId": "5f1c0000-0000-4000-8000-000000000000",
                "eventType": "proposal.viewed",
                "occurredAt": "2026-08-23T09:15:00Z",
                "tenant": "your-tenant-slug",
                "origin": "crm",
                "actor": {
                  "type": "contact",
                  "email": "traveler@example.com",
                  "name": "Ana Silva"
                },
                "payload": {
                  "proposalId": "prop_01H…",
                  "tripId": "trip_01H…",
                  "title": "Bali — 6 nights",
                  "firstView": true,
                  "viewCount": 1
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Return within 10s or the delivery is retried."
          }
        }
      }
    },
    "message.posted": {
      "post": {
        "summary": "Reserved in the allowlist. No code path emits it yet — do not wait on it.",
        "description": "Reserved in the allowlist; no code path emits this event yet.",
        "operationId": "webhook_message_posted",
        "parameters": [
          {
            "name": "X-Connect-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "t=1787654321,v1=<hex>"
            },
            "description": "HMAC-SHA256 of `<t>.<raw body>` keyed by the subscription secret."
          },
          {
            "name": "X-Connect-Tenant",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-tenant-slug"
            }
          },
          {
            "name": "X-Connect-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "message.posted"
            }
          },
          {
            "name": "X-Connect-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Delivery row id. Stable across retries of the same delivery."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "specVersion",
                  "eventId",
                  "eventType",
                  "occurredAt",
                  "tenant",
                  "origin",
                  "actor",
                  "payload"
                ],
                "properties": {
                  "specVersion": {
                    "type": "string",
                    "example": "1.0"
                  },
                  "eventId": {
                    "type": "string",
                    "description": "UUID. Stable across retries — dedupe on it."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "lead.assigned",
                      "lead.stage_changed",
                      "proposal.sent",
                      "proposal.ready",
                      "proposal.viewed",
                      "message.posted"
                    ]
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "tenant": {
                    "type": "string",
                    "example": "your-tenant-slug"
                  },
                  "origin": {
                    "type": "string",
                    "example": "crm"
                  },
                  "actor": {
                    "type": "object",
                    "required": [
                      "type"
                    ],
                    "description": "The traveller the event is about. At least one of email, phone, or externalId is required.",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "contact"
                        ]
                      },
                      "email": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 320
                      },
                      "externalId": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "name": {
                        "type": "string",
                        "maxLength": 200
                      },
                      "phone": {
                        "type": "string",
                        "maxLength": 40
                      }
                    },
                    "anyOf": [
                      {
                        "required": [
                          "email"
                        ]
                      },
                      {
                        "required": [
                          "phone"
                        ]
                      },
                      {
                        "required": [
                          "externalId"
                        ]
                      }
                    ]
                  },
                  "payload": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              },
              "example": {
                "specVersion": "1.0",
                "eventId": "5f1c0000-0000-4000-8000-000000000000",
                "eventType": "message.posted",
                "occurredAt": "2026-08-23T09:15:00Z",
                "tenant": "your-tenant-slug",
                "origin": "crm",
                "actor": {
                  "type": "contact",
                  "email": "traveler@example.com",
                  "name": "Ana Silva"
                },
                "payload": {
                  "messageId": "msg_01H…",
                  "tripId": "trip_01H…"
                }
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Return within 10s or the delivery is retried."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ConnectKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Connect-Key",
        "description": "The visible prefix of an active API key."
      },
      "ConnectTenant": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Connect-Tenant",
        "description": "Tenant slug bound to the key."
      },
      "ConnectSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Connect-Signature",
        "description": "`t=<unix>,v1=<hmac-sha256 of `<t>.<raw body>`>`."
      }
    }
  }
}