Sending events

An event tells Renotify that something happened, and who it happened to. Every live automation listening for the event’s name starts for that contact. Your code never needs to know about templates, channels, consent or timing.

Send an event

POST /api/v1/events, with an API key that has the create permission:

curl https://renotify.app/api/v1/events \
  -H "Authorization: Bearer $RENOTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-1042-due" \
  -d '{
    "name": "payment.due",
    "contact": {
      "external_id": "cus_1042",
      "phone": "+15551234567",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "data": { "plan": "premium" }
    },
    "data": { "amount": "$120.00", "due_date": "1 October", "pay_url": "https://pay.example.com/inv-1042" },
    "occurred_at": "2026-09-29T10:00:00Z"
  }'

Renotify answers straight away with 202 Accepted and the recorded event. Automations start in the background.

Fields

Field
name	Required	The event’s name: lowercase letters, numbers, ., _, : and -, up to 100 characters. Use the past tense or a state, such as order.shipped or payment.due.
contact	Required	Who the event is about. Needs at least one of external_id, phone or email.
contact.external_id		Your own ID for the customer.
contact.phone		In any format; stored in international format. Include the country code.
contact.email
contact.name
contact.data		Custom fields to store on the contact, such as renewal_date (as YYYY-MM-DD) or plan.
contact.marketing_consent		Consent per channel. See below.
data		Anything automations should use, available as {{event.field}}.
occurred_at		When it happened, in ISO 8601. Defaults to now.

The contact

Renotify finds the contact by phone number, then your external_id, then email, and creates them if there’s no match. Details you send update the contact: newer values win. See Matching.

Marketing consent

Send consent only when the customer actually gave it, for example by ticking a box at checkout:

"contact": {
  "phone": "+15551234567",
  "marketing_consent": { "whatsapp": true, "sms": true, "email": false }
}

Keys are channel names (whatsapp, sms, email); values are true or false. Leave it out to keep the contact’s consent as it is. Consent recorded this way has API as its source.

Safe retries

Send an Idempotency-Key header with a value unique to the event, such as invoice-1042-due. If the request is retried with the same key, Renotify returns the original event with 200 OK instead of recording it again, so a customer is never notified twice.

Use a key that identifies the real-world occurrence, not the request: the same invoice falling due should always produce the same key.

Stopping an automation

Send the event that’s the automation’s goal, such as payment.completed, and the automation stops for that customer and records an outcome:

{ "name": "payment.completed", "contact": { "external_id": "cus_1042" }, "data": { "amount": "$120.00" } }

Naming events

• Be consistent. payment.due, payment.completed, payment.failed read well together.
• Name what happened, not what to send. appointment.booked, not send_reminder. Then the same event can start several automations, and you can change the messages without changing code.
• Send details, not text. Send amount and due_date; write the words in the automation.

Recent events

GET /api/v1/events lists recent events, newest first. Filter with ?name=payment.due. Events also appear on the contact’s timeline in the app.

Limits

Events are limited to 1,200 requests a minute per workspace, enough for nightly batches. See Errors and limits.