Send
Events and connections
Tell SendHQ what your contacts do, from your own code, from a payment provider's webhook, or from a spreadsheet, and see what came in and which automations it started.
Three ways in
An automation starts when a contact does something, and stops when they do what it was hoping for. SendHQ learns what a contact did as an event: an email address, a name such as checkout_started, a time, and a few properties. There are three ways to record one, and they all go through the same door: the same contact rules, the same automations started and ended, and the same protection against recording something twice.
- From your code
POST /api/v1/events, with your API key.- From a payment provider or another system
- A connection: a secret address that system posts its webhooks to.
- From a spreadsheet
- Drop an
.xlsxor.csvfile in the dashboard under Contacts → Activity → Connect your app.
Automations are being rolled out workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled from these endpoints, and its connection addresses answer 404.
From your code
Send one event when it happens. A contact that does not exist yet is created, which needs contact.consent_basis: how that person agreed to receive your email. Pass a dedupe_key (or an Idempotency-Key header) so a retry records nothing twice. POST /api/v1/events/batch takes up to 100 at once, and PUT /api/v1/contacts adds or updates a person without recording an event.
{
"email": "ada@example.net",
"event": "checkout_started",
"properties": {
"plan": "pro"
},
"dedupe_key": "checkout_8f3a",
"contact": {
"consent_basis": "Created an account on acme.com and accepted product emails"
}
}From a payment provider: connections
Create a connection in the dashboard, or with POST /api/v1/connections, and give its address to the other system as a webhook endpoint. The address looks like https://sendhq.cc/api/hooks/<token> and is shown once: SendHQ keeps only a hash of the token, so treat it like a password and make a new one (POST /api/v1/connections/:id/address) if it leaks. A workspace can have up to 10 connections.
The address takes POST requests with a JSON body of up to 256 KB and no other authentication. It answers 2xx when the delivery was accepted, including when nothing in it was worth recording; 404 for an address that does not exist or is switched off; 401 for a bad signature; and 429 with Retry-After after 120 deliveries in a minute. A delivery that is sent again is recorded once, because the provider's event ID becomes the dedupe key.
Every connection needs a consent_basis, recorded on each contact it creates, and may have an event_prefix such as stripe_. The last 50 deliveries are kept with what came of each, in plain words: "Recorded 2 events", "Skipped: no email address", "Refused: bad signature". Payloads are not stored.
Stripe
Add the address in Stripe as a webhook endpoint, then paste the endpoint's signing secret (whsec_…) into the connection. Once a secret is set, a delivery whose Stripe-Signature is missing, wrong, or more than five minutes old is refused.
checkout.session.completedcheckout_completed, andpaidwhen the session'spayment_statusispaid.checkout.session.async_payment_succeeded/…failedpaid/payment_failed.checkout.session.expiredcheckout_abandoned, withrecovery_urlwhen Stripe provides one.invoice.paidpaidfor a subscription's first invoice or an invoice of its own;subscription_renewedfor a renewal. A subscription's first payment arrives both as a checkout and as an invoice, and is recorded once.invoice.payment_failedpayment_failed, withinvoice_url.customer.subscription.createdsubscription_started, once the subscription is active or trialing.customer.subscription.updatedplan_changedwhen the price changed.customer.subscription.deletedsubscription_cancelled.
The email address is read from customer_details.email, customer_email, or receipt_email. A subscription event names only the customer; SendHQ uses the address it saw for that customer in an earlier delivery, and skips the event if it has none. Properties include amount, currency, and plan where the payload has them, and amount_display: the amount as a person reads it, such as $49.50, for an email to print.
Dodo Payments
Add the address as a webhook in Dodo Payments and paste its signing secret into the connection. Deliveries are verified with the Standard Webhooks scheme (webhook-id, webhook-timestamp, webhook-signature).
payment.succeededpaidpayment.failed,subscription.on_hold,subscription.failedpayment_failedsubscription.activesubscription_startedsubscription.renewedsubscription_renewedsubscription.cancelled,subscription.expiredsubscription_cancelledsubscription.plan_changedplan_changed
Any other system
A generic connection reads any JSON with a small mapping of dotted paths: where the email is, where the payload names what happened (event) or one fixed event_name, and optionally the time, a unique id (so a retried delivery is recorded once), and the fields to keep as properties. Without keep, the top-level text, number, and boolean fields are kept. A name such as Order Placed becomes the event order_placed. Try a mapping on a sample before relying on it: POST /api/v1/connections/test returns the events a payload would record and writes nothing.
{
"name": "My shop",
"kind": "generic",
"consent_basis": "Bought from our shop and accepted product emails",
"mapping": {
"email": "customer.email",
"event": "type",
"time": "created_at",
"id": "id",
"keep": [
"plan",
"total"
]
}
}From a spreadsheet
In the dashboard, drop an .xlsx or .csv file of up to 5,000 rows and 5 MB. SendHQ finds the email column and asks what each other column is: a detail about the person (kept as a contact field), the date they did something, or nothing. The people are added through the contact import with the consent basis you choose. If a date column is chosen, one event per person is recorded at that date, named once for the whole file, and each behaves exactly as an API event does: before anything is recorded the dashboard asks POST /api/v1/events/preview how many of these people would start which automation, and says so.
Events the template library starts on
The template library (GET /api/v1/automation-library, or New automation in the dashboard) has finished emails for welcome, onboarding, trial, abandoned checkout, failed payment, receipt, upgrade, cancellation, and winback. Each suggests the event that starts it and the event that ends it. Where a payment connection records the event, the template uses that name: paid, payment_failed, checkout_abandoned, checkout_completed, subscription_started, subscription_cancelled, and plan_changed. The others your own code sends:
signed_up- Someone created an account. Starts the welcome emails, the onboarding tips, and the nudge to finish setup.
activated- They finished setup. Ends the onboarding tips and the nudge.
trial_ending- Three days before a trial ends. Starts "Trial ends in 3 days". Send it with
trial_end_dateas you want it printed. trial_ended- The trial is over. Starts "Trial ended" when that email is used alone.
usage_limit_near- An account is close to a plan limit. Send
usage_used,usage_limit, andplan.
A start is a suggestion: change it on the automation at any time. An automation starts on an event, or by adding people one at a time; it cannot yet start on a date saved on a contact, which is why a trial is announced by an event. A receipt prints amount_display; for a paid event from your own code, send amount and currency and SendHQ writes the amount out, such as $49.50.
Seeing what came in
The Activity tab of Contacts lists every event, newest first: who, what they did, when, and what it set off. The same feed is GET /api/v1/events, with filters for one contact, one event name, and a date range; each item says where it came from (your code, a connection by name, a spreadsheet, or SendHQ itself) and which automations it started, ended, or converted. GET /api/v1/events/names lists the kinds of event recorded in the last 30 days.