Matchai Docs

A new leadComing soon

Event lead.created.

Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.

Coming soon. Event lead.created. A new lead reached the account: an enquiry from a listing, the Matchai Site, the Matchai Page or your website, a visit request, or someone saving a listing. data.object is the contact.

Verify Matchai-Signature before trusting the body, and answer with any 2xx within 10 seconds.

Scopes to receive it: contacts:read

Pricing: Included with the connection.

Header Parameters

Matchai-Signature*string

t=<unix seconds>,v1=<hex HMAC-SHA256>. During a secret rotation it carries two v1 values.

Matchai-Event-Id*string

Same as the body’s id. Use it to ignore duplicates.

Matchai-Delivery-Attempt*integer

Attempt number, from 1.

Range1 <= value

Request Body

application/json
  1. body

The body of every webhook delivery, and of GET /events.

id*string

Event id. Deliveries can repeat: use it to ignore duplicates.

Length1 <= length <= 64
type*string

New event types may be added. Ignore types you do not know.

Value in"lead.created""contact.created""contact.updated""contact.converted""contact.deleted""conversation.created""message.received""message.sent""appointment.requested""appointment.booked""appointment.rescheduled""appointment.cancelled""listing.created""listing.updated""listing.published""listing.unpublished""listing.archived""listing.deleted""listing.saved""listing.generation.completed""document.created""drop_link.upload_received""invitation.accepted""notification.created""approval.resolved""webhook.test"
created_at*string

When it happened.

Formatdate-time
api_version*string
test_mode*boolean

Sent for a test connection or by POST /webhook-subscriptions/{id}/test.

account*
data*

Response Body

Received. Any 2xx status works. Anything else, or no answer within 10 seconds, is retried.

Example Requests
POST/lead.created
Request Body
application/json
{  "id": "0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a",  "type": "lead.created",  "created_at": "2026-10-16T19:12:45Z",  "api_version": "v1",  "test_mode": false,  "account": {    "user_id": "3f1c9a2e-7b44-4d0e-9c1a-5e8f2b6d4a10",    "professional_id": "8a2d4f6b-1c3e-4a5b-9d7f-0e2c4b6a8d1f"  },  "data": {    "object": {      "id": "c5d8e1f2-3a4b-4c6d-9e8f-7a6b5c4d3e2f",      "type": "lead",      "first_name": "Julien",      "last_name": "Bouchard",      "display_name": "Julien Bouchard",      "email": "julien.bouchard@example.com",      "phone": "+15145550142",      "company": null,      "profession": null,      "notes": "Looking for a 2-bedroom on the Plateau, close to the orange line.",      "source": "listing",      "source_listing_id": "b7e4c2a1-9f3d-4e6b-8a5c-1d2f3e4a5b6c",      "matchai_user": {        "user_id": "1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a",        "username": "julienb",        "avatar_url": null      },      "conversation_id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",      "erased": false,      "lead": {        "stage": "qualify",        "temperature": "warm",        "readiness": "considering",        "lifecycle_stage": "new",        "score": 62,        "budget": {          "min": 550000,          "max": 700000,          "currency": "CAD"        },        "timeline": "Within 3 months",        "preferences": {          "bedrooms": 2,          "bathrooms": 1,          "min_sqft": 850,          "max_sqft": null,          "property_types": [            "condo"          ],          "areas": [            "Plateau-Mont-Royal",            "Rosemont"          ],          "features": [            "Balcony"          ]        },        "updated_at": "2026-10-17T16:20:00Z"      },      "client": null,      "professional": null,      "created_at": "2026-10-16T19:12:44Z",      "updated_at": "2026-10-17T16:20:00Z"    }  }}
Header Parameters
{  "Matchai-Signature": "t=1760627565,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",  "Matchai-Event-Id": "string",  "Matchai-Delivery-Attempt": 1}