> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequencehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook events

> Reference for the events Sequence sends, the payload envelope, signature header, and delivery behavior.

This page is the reference for what Sequence sends and how. For a step-by-step integration walkthrough, see [Set up webhooks](https://docs.sequencehq.com/reference/webhooks.md).

## Request format

Sequence delivers webhooks as `POST` requests with `Content-Type: application/json`. Every payload has the same envelope:

```typescript theme={null}
{
  notificationType: string;
  sequenceAccountId: string;
  resourceType?: string;
  resourceId?: string;
  resource?: Record<string, any>;
}
```

The `resource` field contains the state of the resource that triggered the event.

### Example payload

A `BILLING_SCHEDULE_CREATED` delivery looks like this. The `prices` and `phases` arrays are simplified for readability; in real deliveries they contain the full pricing and phase structure for the schedule.

```json theme={null}
{
  "notificationType": "BILLING_SCHEDULE_CREATED",
  "sequenceAccountId": "019e6eb6-db30-7cf2-8017-06a5a2859e13",
  "resourceType": "BillingScheduleResponse",
  "resourceId": "019e6eb6-cd26-74eb-808b-e7a37f1c4ef1",
  "resource": {
    "id": "019e6eb7-0c24-765b-8446-6fb074f018d7",
    "status": "DRAFT",
    "startDate": "2026-04-27",
    "endDate": "2027-04-26",
    "customerId": "019e6eb7-353e-7ddf-a5ae-75f2d9509d6b",
    "recurrenceDayOfMonth": 1,
    "autoIssueInvoices": false,
    "rollUpBilling": false,
    "defaultDueDateDays": 30,
    "prices": [],
    "phases": [],
    "taxRates": [],
    "attachmentAssets": [],
    "integrationIds": [],
    "createdAt": "2026-04-27T17:04:11.601533Z",
    "updatedAt": "2026-04-27T17:04:11.601533Z"
  }
}
```

## `Sequence-Signature` header

Every webhook includes a `Sequence-Signature` header containing a timestamp and an HMAC signature:

```
Sequence-Signature: t=1748866120822,s=6be6887a470c20978427ff89941ebecb83b2804ceed66fd93b3afc00de2e9f11
```

* `t` is the delivery timestamp, in Unix milliseconds.
* `s` is an HMAC-SHA256 signature of `${t}.${rawBody}`, computed using the webhook's signing secret.

The timestamp is part of the signed payload, so receivers can reject deliveries with a stale `t` to mitigate replay attacks.

For working verification code, see [Verify the signature](https://docs.sequencehq.com/reference/webhooks.md#verify-the-signature) in the integration guide.

## Delivery

* **Acknowledgment.** Sequence considers any `2xx` response a successful delivery.
* **Retries.** Any non-`2xx` response causes Sequence to retry. Retries continue for up to **24 hours**, with exponential backoff.

New event types may be added over time. Handlers should accept and ignore types they don't recognize.

## Event catalog

| Event | Resource type | Triggered when |
| - | - | - |
| `CUSTOMER_CREATED` | Customer | A customer is created |
| `CUSTOMER_UPDATED` | Customer | A customer is updated |
| `CUSTOMER_ARCHIVED` | Customer | A customer is archived |
| `CUSTOMER_ALIAS_CREATED` | CustomerAlias | An alias is added to a customer |
| `CUSTOMER_ALIAS_UPDATED` | CustomerAlias | An alias's label is changed |
| `CUSTOMER_ALIAS_DELETED` | CustomerAlias | An alias is removed from a customer |
| `INVOICE_CREATED` | Invoice | An invoice is created |
| `INVOICE_ISSUED` | Invoice | An invoice is issued |
| `INVOICE_UPDATED` | Invoice | An invoice is updated |
| `INVOICE_REMINDER_SENT` | Invoice | A dunning payment reminder is sent to a customer |
| `BILLING_SCHEDULE_CREATED` | BillingSchedule | A billing schedule is created |
| `BILLING_SCHEDULE_UPDATED` | BillingSchedule | A billing schedule is updated |
| `BILLING_SCHEDULE_ARCHIVED` | BillingSchedule | A billing schedule is archived |
| `CREDIT_NOTE_CREATED` | CreditNote | A credit note is created |
| `CREDIT_NOTE_UPDATED` | CreditNote | A credit note is updated |
| `CREDIT_NOTE_ISSUED` | CreditNote | A credit note is issued |
| `QUOTE_PUBLISHED` | Quote | A quote is published |
| `QUOTE_SIGNED` | Quote | A quote is signed |
| `QUOTE_ACCEPTED` | Quote | A quote is accepted |
| `MERCHANT_UPDATED` | Merchant | Merchant-level settings are updated |
| `WATCHTOWER_TASK_ASSIGNED` | WatchtowerTask | A Watchtower review task is assigned to a user |

## Customer alias events

Customer webhooks don't include the customer's aliases. To find out when an alias changes, subscribe to the alias events. Each one carries the single alias that changed.

| Change | Event sent |
| - | - |
| Create a customer with aliases (`POST /customers`) | `CUSTOMER_ALIAS_CREATED` for each alias |
| Update a customer's aliases (`PUT /customers/{id}`, or editing the customer in the dashboard) | `CUSTOMER_ALIAS_CREATED` for each alias added, `CUSTOMER_ALIAS_DELETED` for each alias removed |
| Create an alias (`POST /customer-aliases`, or linking an alias to a customer in the dashboard) | `CUSTOMER_ALIAS_CREATED` |
| Change an alias's label (`PUT /customer-aliases/{id}`) | `CUSTOMER_ALIAS_UPDATED` |
| Delete an alias (`DELETE /customer-aliases/{id}`) | `CUSTOMER_ALIAS_DELETED` |

These are sent alongside the customer events, not instead of them. For example, updating a customer to add an alias sends both `CUSTOMER_UPDATED` and `CUSTOMER_ALIAS_CREATED`. Archiving a customer sends `CUSTOMER_ARCHIVED` and no alias events.

The `resource` is the alias as the [customer alias endpoints](https://docs.sequencehq.com/reference/latest/customer/list-all-customer-aliases.md) return it. `label` is left out when the alias has none, and `deletedAt` is only included in `CUSTOMER_ALIAS_DELETED`.

Webhooks can arrive out of order. Use `updatedAt` to order changes to the same alias: it's set every time the alias is created, has its label changed, or is deleted.

```json theme={null}
{
  "notificationType": "CUSTOMER_ALIAS_CREATED",
  "sequenceAccountId": "af9b5988-1d7b-45f6-a188-326df5e59b24",
  "resourceType": "CustomerAlias",
  "resourceId": "01849e70-0a0f-72ca-ba07-5557dd734d43",
  "resource": {
    "id": "01849e70-0a0f-72ca-ba07-5557dd734d43",
    "sequenceAccountId": "af9b5988-1d7b-45f6-a188-326df5e59b24",
    "customerId": "01849e70-703e-705a-b59a-d3fd575587e0",
    "value": "external-customer-alias-123",
    "label": "CRM ID",
    "createdAt": "2022-10-01T00:00:00Z",
    "updatedAt": "2022-10-01T00:00:00Z"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.