---
title: Events and connections | SendHQ Docs
description: "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."
canonical: https://sendhq.cc/docs/events
last-updated: 2026-09-07
updated: 2026-09-07
---
# 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 `.xlsx` or `.csv` file 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.

```json
{
  "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.completed`**

`checkout_completed`, and `paid` when the session's `payment_status` is `paid`.

**`checkout.session.async_payment_succeeded` / `…failed`**

`paid` / `payment_failed`.

**`checkout.session.expired`**

`checkout_abandoned`, with `recovery_url` when Stripe provides one.

**`invoice.paid`**

`paid` for a subscription's first invoice or an invoice of its own; `subscription_renewed` for a renewal. A subscription's first payment arrives both as a checkout and as an invoice, and is recorded once.

**`invoice.payment_failed`**

`payment_failed`, with `invoice_url`.

**`customer.subscription.created`**

`subscription_started`, once the subscription is active or trialing.

**`customer.subscription.updated`**

`plan_changed` when the price changed.

**`customer.subscription.deleted`**

`subscription_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.succeeded`**

`paid`

**`payment.failed`, `subscription.on_hold`, `subscription.failed`**

`payment_failed`

**`subscription.active`**

`subscription_started`

**`subscription.renewed`**

`subscription_renewed`

**`subscription.cancelled`, `subscription.expired`**

`subscription_cancelled`

**`subscription.plan_changed`**

`plan_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.

```json
{
  "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_date` as 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`, and `plan`.

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.
