Emit a Notification Event

POST /notifications/events

Post Event

cURL

curl --request POST \
  --url https://api.example.com/notifications/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event_type": "<string>",
  "entity_id": "<string>",
  "entity_type": "deal",
  "payload": {}
}
'

202

{}

New to notifications? See the Notifications guide for how the system works end-to-end — this API only covers the manual producer escape hatch, not the in-app feed itself.

Emitting an event is treated as a deal-management action, gated the same as a deal write, so a read-only member can’t inject notifications for the org. This lets a write path that bypasses the normal deal handlers (an import job, a script) register the same kind of event those handlers emit automatically. Only entity_type: "deal" is supported today — any other value is rejected with 400. Delivery is best-effort: this call queues the event onto the org’s per-org notification actor (a Temporal workflow) and returns immediately; it never renders or sends anything synchronously.

Anti-spoofing on deal events. Whatever payload you send for a deal event is not trusted as-is. The backend looks up the real deal row for entity_id in the caller’s org and overwrites deal_id, deal_name, value, currency, owner_id, and new_owner_id with the actual database values before the event is delivered. This exists specifically so the escape hatch can’t be used to spoof a deal’s name/value/owner, or to fan an “assigned to you” notification at a user who isn’t really the deal’s owner. Non-sensitive display hints you send through (e.g. field, old, new, stage names) are preserved as-is. If the deal isn’t visible in the caller’s org, the call fails with 404 rather than silently accepting a fake payload.

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Response

202 Accepted

Field	Type	Description
accepted	boolean	Whether the Temporal actor accepted the event. emit_event swallows its own errors (a queueing failure never surfaces as an HTTP error), so false means the event was silently dropped — check application logs, not this field, if events seem to be going missing.

Errors

Status	Cause
400 Bad Request	event_type isn’t a known registered event, or entity_type isn’t "deal".
403 Forbidden	No active organization on the token, or the token lacks a CRM manage scope.
404 Not Found	entity_id doesn’t resolve to a deal visible in the caller’s org.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

event_type · string · required

A registered event type, e.g. "deal.stage_changed" — see GET /notifications/event-catalog for the full list.

entity_id · string · required

UUID of the entity the event is about — currently always a deal id.

entity_type · string · default: deal

The kind of entity entity_id refers to; only "deal" is supported today, anything else is rejected with 400.

payload · Payload · object | null

Client-supplied event details; for deal events the sensitive fields (name/value/owner) are overwritten server-side from the real deal row before delivery.

Response

202

application/json

Successful Response

The response is of type Response Post Event Notifications Events Post · object.