Webhooks overview - Notealy

Outbound webhooks let your system react to changes inside Notealy without polling. Configure a subscription URL in Settings → Webhooks, and Notealy will POST a signed JSON envelope every time a matching event occurs.

Envelope

{
  "id": "evt_01J...",
  "type": "contact.tag_added",
  "created": "2026-05-04T18:21:00.000Z",
  "api_version": "1",
  "data": {
    "contactId": "01J...",
    "tagId": "01J...",
    "tagName": "web-lead",
    "organizationId": "01J..."
  }
}

Headers:

Header	Purpose
`X-Notealy-Delivery-Id`	Unique per delivery attempt
`X-Notealy-Event-Type`	Same as `type` in the body, for cheap routing
`X-Notealy-Signature`	HMAC signature — see Signing
`User-Agent`	`Notealy-Webhooks/1`

Available events

Event	When it fires
`contact.created`	A new contact is created (any source — UI, public API, import)
`contact.stage_changed`	A contact moves between pipeline stages
`contact.assigned`	A contact is assigned to a user
`deal.created`	A new deal is created
`deal.updated`	A deal’s fields are updated
`deal.won`	A deal is moved to a `WON` stage
`deal.lost`	A deal is moved to a `LOST` stage
`message.sent`	A message is sent (any channel)
`message.received`	A message is received (any channel)

Subscriptions accept either a specific list of event types or * for all events.

Responding

Return any 2xx within 25 seconds. Anything else (including timeouts) is treated as failure and triggers retries — see Retries. Treat webhooks as at-least-once: Notealy may deliver the same event more than once on retry. Use X-Notealy-Delivery-Id to deduplicate on your side.