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

# Destinations

> Register and configure webhook destinations for Recurr's event stream. HTTPS webhooks + email fallback, per-destination PII handling.

Destinations are the endpoints where Recurr delivers webhook events. Each destination has its own signing secret, event-type filter, and PII-handling rules.

A single tenant can register multiple destinations — e.g., separate destinations for your CS tool, your warehouse, your MMP, and your CDP. Each receives a tailored subset of events with the right PII mode for that destination type.

## Destination types

### HTTPS webhook

Standard delivery to any HTTPS endpoint that accepts POST requests.

| Field            | Type      | Description                                                                                  |
| ---------------- | --------- | -------------------------------------------------------------------------------------------- |
| `url`            | string    | Target URL. Must be HTTPS.                                                                   |
| `event_types`    | string\[] | Event-type filter; omit to receive all events                                                |
| `pii_mode`       | string    | `"full"`, `"hashed_only"`, or `"minimal"` (see [PII modes](#pii-modes))                      |
| `signing_secret` | string    | Generated at registration. Used for HMAC signing. Store securely on your side.               |
| `schema_version` | string    | Pinned schema version (e.g., `v1`). Defaults to current.                                     |
| `description`    | string    | Human-readable label for the destination (e.g., "Production Zendesk", "Analytics warehouse") |

### Email fallback

For customers without a CS-tool webhook endpoint, deliver `ticket.submitted` events as emails to a support address.

| Field                 | Type    | Description                                                                                                                      |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `email`               | string  | Target support email (e.g., `support@yourapp.com`)                                                                               |
| `reply_to_subscriber` | boolean | If `true`, sets the email `Reply-To` header to the subscriber's email so your team replies directly to them                      |
| `subject_template`    | string  | Optional subject-line template with subscriber context interpolation (e.g., `"[Billing] {{subscriber.email}} — {{data.topic}}"`) |

Email fallback only delivers `ticket.submitted` events. For everything else, register an HTTPS webhook.

## PII modes

Recurr's envelope always contains both raw and hashed email fields. The destination's `pii_mode` determines which fields actually forward to the endpoint:

| Mode          | `subscriber.email` (raw) | `subscriber.email_hashed` | `data` fields containing PII                                                      |
| ------------- | ------------------------ | ------------------------- | --------------------------------------------------------------------------------- |
| `full`        | Included                 | Included                  | Included as-is                                                                    |
| `hashed_only` | Stripped                 | Included                  | Stripped or hashed                                                                |
| `minimal`     | Stripped                 | Stripped                  | Stripped; only event ID, type, subscriber ID, subscription ID, timestamp included |

### Recommended defaults by destination category

| Destination category          | Recommended `pii_mode`                   | Rationale                                                                              |
| ----------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- |
| BI / data warehouse           | `full`                                   | Customer's own data, internal use                                                      |
| CS tool                       | `full`                                   | Needed for ticket context + agent workflow                                             |
| Product analytics             | `hashed_only`                            | Customer's data, but analytics tools often share infrastructure with analytics vendors |
| Mobile measurement (MMP)      | `hashed_only`                            | Sent to ad platforms; raw PII shouldn't flow                                           |
| Customer data platforms (CDP) | `hashed_only`                            | CDPs distribute to downstream including ad platforms                                   |
| Custom / internal pipeline    | `full` or `hashed_only` depending on use | Customer choice                                                                        |

Customers can override per-destination if their requirements differ.

## Registration

### Today (pre-customer-self-serve)

Destinations are registered during customer onboarding by Recurr's implementation team. The team scopes destinations from the customer's stack inventory during pilot setup, generates signing secrets, and configures PII modes per destination category.

### Future (post-customer-#5)

Self-serve destination registration available via the customer dashboard. Customers add HTTPS endpoints, configure event-type filters and PII modes, retrieve signing secrets — all without Recurr operator involvement.

## API reference (future)

When self-serve registration ships, the destination management API will be:

### Create destination

```http theme={null}
POST https://api.recurr.dev/v1/destinations
Authorization: Bearer <recurr_api_key>
Content-Type: application/json

{
  "type": "https_webhook",
  "url": "https://your-app.com/webhooks/recurr",
  "event_types": ["subscription.*", "payment.*"],
  "pii_mode": "full",
  "description": "Production analytics warehouse"
}
```

Response:

```json theme={null}
{
  "id": "dest_01HQX...",
  "type": "https_webhook",
  "url": "https://your-app.com/webhooks/recurr",
  "event_types": ["subscription.*", "payment.*"],
  "pii_mode": "full",
  "signing_secret": "whsec_<one-time-display>",
  "schema_version": "v1",
  "status": "active",
  "created_at": "2026-05-22T13:34:56Z"
}
```

<Warning>
  The `signing_secret` is shown once at creation only. Store it securely. If lost, rotate the secret via the destination management API.
</Warning>

### List destinations

```http theme={null}
GET https://api.recurr.dev/v1/destinations
Authorization: Bearer <recurr_api_key>
```

### Update destination

```http theme={null}
PATCH https://api.recurr.dev/v1/destinations/dest_01HQX...
Authorization: Bearer <recurr_api_key>
Content-Type: application/json

{
  "event_types": ["subscription.*", "payment.*", "motion.*"],
  "pii_mode": "hashed_only"
}
```

### Rotate signing secret

```http theme={null}
POST https://api.recurr.dev/v1/destinations/dest_01HQX.../rotate-secret
Authorization: Bearer <recurr_api_key>
```

Returns a new signing secret. The old secret remains valid for 24 hours to allow your endpoint to roll over without missed deliveries.

### Disable / delete destination

```http theme={null}
DELETE https://api.recurr.dev/v1/destinations/dest_01HQX...
Authorization: Bearer <recurr_api_key>
```

Soft-deletes; recoverable for 30 days. Hard delete via `?force=true`.

## Custom destinations

Beyond standard categories, any HTTPS endpoint that accepts POST requests works. Common cases:

* Internal data pipelines (your engineering team's custom event consumer)
* Custom CRM integrations (HubSpot, Salesforce custom objects, etc.)
* Partner systems (white-label partner needs subscription state)
* Anti-fraud / risk vendors (Sift, Forter, etc.)
* BI tooling (custom warehouses, internal Snowflake, etc.)

The mechanic is identical: register the HTTPS URL, set the event-type filter, choose the PII mode, receive the signing secret. Same signed payload, same retry semantics, same idempotency guarantees.