Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1206,6 +1206,28 @@ Validated sends append one record per email to the `resend.send_attempts` store

Read attempts with `getResendStore(store).sendAttempts.all()` from `@emulators/resend`, or inspect the persisted state. Shared adapter snapshots use the key `resend:resend.send_attempts`. Attempts and recipient restrictions survive saved-state restoration, including rejected sends. There is no additional Resend API endpoint for attempts. A rejected send has an attempt without an email; a send that never happened has neither.

### Webhooks

Register endpoints with `POST /webhooks` (`endpoint` and `events`) on hosts listed in `resend.webhook_hosts`, or seed them with `resend.webhooks`. Deliveries carry Svix `svix-id`, `svix-timestamp`, and `svix-signature` headers, signed with the webhook's `whsec_` signing secret as Resend signs them, so `resend.webhooks.verify()` and the `svix` library accept them. `GET /webhooks/:id` returns the secret. A `3xx` response counts as a failed attempt and is not followed, as Svix treats redirects.

```yaml
resend:
webhooks:
- endpoint: http://localhost:3000/api/webhooks/resend
events: [email.sent, email.delivered]
```

Without `events`, a seeded webhook subscribes to every event the emulator sends. Without `signing_secret`, it gets a secret derived from the endpoint URL that stays the same across resets and restarts.

Webhooks created or updated through the API must use an `http` or `https` endpoint on a host listed in `resend.webhook_hosts`. Without that setting, the API registers no webhooks: `POST /webhooks` and an endpoint change through `PATCH /webhooks/:id` return `403 validation_error`. A host missing from the list also returns `403 validation_error`, and an endpoint that isn't an HTTP URL returns `422 validation_error`. Seeded webhooks come from your own config and are not checked. Hosts match by exact name, without ports or wildcards. To register a local receiver or a Docker Compose service through the API, list its host:

```yaml
resend:
webhook_hosts: [localhost, app]
```

The emulator sends deliveries from its own host and accepts any API key, so this list decides which hosts its clients can make it contact. Keep it to the receivers you expect, especially when the emulator listens on a network address. This is a local control, not part of Resend's API.

## Linear API

Stateful Linear GraphQL API emulation with seeded organizations, users, teams, workflow states, issues, comments, labels, projects, cycles, OAuth apps, tokens, webhooks, and basic agent sessions. GraphQL reads and writes mutate in-memory state and use Relay-style connections with opaque cursors. OAuth supports authorization code, PKCE, refresh token, revoke, client credentials, and `actor=app` tokens for local app-actor tests. Supported writes dispatch Linear-shaped webhook payloads with `Linear-Delivery`, `Linear-Event`, and `Linear-Signature` headers when webhooks are configured.
Expand Down
31 changes: 31 additions & 0 deletions apps/web/content/docs/resend.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,37 @@ Read attempts with `getResendStore(store).sendAttempts.all()` from `@emulators/r
- `GET /audiences/:audience_id/contacts` — list contacts
- `DELETE /audiences/:audience_id/contacts/:id` — delete contact

## Webhooks

- `POST /webhooks` — create webhook and return its `signing_secret`
- `GET /webhooks` — list webhooks
- `GET /webhooks/:id` — get webhook, including its `signing_secret`
- `PATCH /webhooks/:id` — update `endpoint`, `events`, or `status`
- `DELETE /webhooks/:id` — delete webhook

Deliveries are signed with Svix, as Resend signs them. Each request carries `svix-id`, `svix-timestamp`, and `svix-signature` headers, so `resend.webhooks.verify()` and the `svix` library accept them when given the webhook's signing secret. The emulator sends `email.sent` and `email.delivered` for each email that isn't scheduled, `domain.created` and `domain.deleted`, and `contact.created` and `contact.deleted`. A webhook receives only the events in its `events` list, and a `disabled` webhook receives none. Each event is attempted once, with a 10-second timeout and no retries. A `3xx` response counts as a failed attempt and is not followed, as Svix treats redirects.

Webhooks can also be seeded:

```yaml
resend:
webhooks:
- endpoint: http://localhost:3000/api/webhooks/resend
events: [email.sent, email.delivered]
signing_secret: whsec_emulateTestSecretDoNotUseInProd0
```

Without `events`, a seeded webhook subscribes to every event the emulator sends. Without `signing_secret`, it gets a secret derived from the endpoint URL that stays the same across resets and restarts; read it with `GET /webhooks/:id`.

Webhooks created or updated through the API must use an `http` or `https` endpoint on a host listed in `resend.webhook_hosts`. Without that setting, the API registers no webhooks: `POST /webhooks` and an endpoint change through `PATCH /webhooks/:id` return `403 validation_error`. A host missing from the list also returns `403 validation_error`, and an endpoint that isn't an HTTP URL returns `422 validation_error`. Seeded webhooks come from your own config and are not checked. Hosts match by exact name, without ports or wildcards. To register a local receiver or a Docker Compose service through the API, list its host:

```yaml
resend:
webhook_hosts: [localhost, app]
```

The emulator sends deliveries from its own host and accepts any API key, so this list decides which hosts its clients can make it contact. Keep it to the receivers you expect, especially when the emulator listens on a network address. This is a local control, not part of Resend's API.

## Inbox

- `GET /inbox` — list captured emails
Expand Down
2 changes: 1 addition & 1 deletion apps/web/tests/fixtures/docs-baseline.json
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@
"description": "Local drop-in replacement services for CI and no-network sandboxes. Fully stateful, production-fidelity API emulation.",
"ogImage": "/og/resend",
"ogTitle": "Resend | emulate",
"headings": ["Emails", "Idempotency", "Domains", "API Keys", "Audiences & Contacts", "Inbox"]
"headings": ["Emails", "Idempotency", "Domains", "API Keys", "Audiences & Contacts", "Webhooks", "Inbox"]
},
"/docs/stripe": {
"title": "Stripe | emulate",
Expand Down
16 changes: 16 additions & 0 deletions packages/@emulators/core/src/__tests__/webhooks.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,22 @@ describe("WebhookDispatcher", () => {
expect(mockFetch).not.toHaveBeenCalled();
});

it("follows redirects unless the subscription opts out", async () => {
const d = new WebhookDispatcher();
d.register({ url: "https://hooks.example/default", events: ["push"], active: true, owner: "o" });
d.register({
url: "https://hooks.example/strict",
events: ["push"],
active: true,
owner: "o",
followRedirects: false,
});

await d.dispatch("push", undefined, {}, "o");

expect(mockFetch.mock.calls.map((c) => (c[1] as RequestInit).redirect)).toEqual(["follow", "manual"]);
});

it("records deliveries with status and success from the response", async () => {
const d = new WebhookDispatcher();
const sub = d.register({
Expand Down
3 changes: 3 additions & 0 deletions packages/@emulators/core/src/webhooks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ export interface WebhookSubscription {
secret?: string;
owner: string;
repo?: string;
/** When false, a 3xx response is recorded as a failed delivery instead of being followed. Defaults to true. */
followRedirects?: boolean;
}

export interface WebhookDelivery {
Expand Down Expand Up @@ -182,6 +184,7 @@ export class WebhookDispatcher {
method: "POST",
headers,
body,
redirect: sub.followRedirects === false ? "manual" : "follow",
signal: this.options.signal
? AbortSignal.any([this.options.signal, AbortSignal.timeout(10000)])
: AbortSignal.timeout(10000),
Expand Down
23 changes: 23 additions & 0 deletions packages/@emulators/resend/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,15 @@ Read attempts with `getResendStore(store).sendAttempts.all()` from `@emulators/r
- `GET /audiences/:audience_id/contacts` — list contacts
- `DELETE /audiences/:audience_id/contacts/:id` — delete contact

### Webhooks
- `POST /webhooks` — create webhook and return its `signing_secret`
- `GET /webhooks` — list webhooks
- `GET /webhooks/:id` — get webhook, including its `signing_secret`
- `PATCH /webhooks/:id` — update `endpoint`, `events`, or `status`
- `DELETE /webhooks/:id` — delete webhook

Deliveries are signed with Svix, as Resend signs them. Each request carries `svix-id`, `svix-timestamp`, and `svix-signature` headers, so `resend.webhooks.verify()` and the `svix` library accept them when given the webhook's signing secret. The emulator sends `email.sent` and `email.delivered` for each email that isn't scheduled, `domain.created` and `domain.deleted`, and `contact.created` and `contact.deleted`. A webhook receives only the events in its `events` list, and a `disabled` webhook receives none. Each event is attempted once, with a 10-second timeout and no retries. A `3xx` response counts as a failed attempt and is not followed, as Svix treats redirects.

### Inbox
- `GET /inbox` — list captured emails
- `GET /inbox/:id` — view captured email
Expand All @@ -74,8 +83,22 @@ resend:
- name: example.com
api_keys:
- name: default
webhooks:
- endpoint: http://localhost:3000/api/webhooks/resend
events: [email.sent, email.delivered]
```

Without `events`, a seeded webhook subscribes to every event the emulator sends. Without `signing_secret`, it gets a secret derived from the endpoint URL that stays the same across resets and restarts; read it with `GET /webhooks/:id`.

Webhooks created or updated through the API must use an `http` or `https` endpoint on a host listed in `resend.webhook_hosts`. Without that setting, the API registers no webhooks: `POST /webhooks` and an endpoint change through `PATCH /webhooks/:id` return `403 validation_error`. A host missing from the list also returns `403 validation_error`, and an endpoint that isn't an HTTP URL returns `422 validation_error`. Seeded webhooks come from your own config and are not checked. Hosts match by exact name, without ports or wildcards. To register a local receiver or a Docker Compose service through the API, list its host:

```yaml
resend:
webhook_hosts: [localhost, app]
```

The emulator sends deliveries from its own host and accepts any API key, so this list decides which hosts its clients can make it contact. Keep it to the receivers you expect, especially when the emulator listens on a network address. This is a local control, not part of Resend's API.

## Links

- [Full documentation](https://emulate.dev)
Expand Down
Loading
Loading