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

# Connect Segment, Stripe, HubSpot, and Intercom

> Wire external sources into Notifizz — webhook setup per provider, signature schemes, mapping events to campaigns, debugging signature failures.

# Integrations guide

Notifizz ingests events from external sources via dedicated webhook endpoints. This guide walks through setting up each connector — Segment, Stripe, HubSpot, Intercom — from "zero" to "campaign fires from a provider event".

The exact wire format per provider is in [connector webhooks reference](/docs/sdks/how-to/connector-webhooks). This page is task-oriented; jump there when you need the headers and HMAC formulas.

## TL;DR

* Each provider has a dedicated `POST /v1/webhooks/{provider}/:sourceId` endpoint.
* The dashboard mints a `sourceId` and `verificationSecret` per source.
* Configure the webhook on the provider side with the URL + secret.
* Notifizz verifies the signature, maps the provider event to the Notifizz event grammar, and feeds it into the same pipeline as `client.track()` calls.

## Common flow

The setup is the same shape for every provider:

<Steps>
  <Step title="Create a source in the dashboard">
    Pick the provider, name the source. The dashboard mints a `sourceId` and a `verificationSecret`. Both are needed in the next step.
  </Step>

  <Step title="Configure the webhook on the provider">
    Each provider has its own admin UI; the URL pattern is `https://eu.api.notifizz.com/v1/webhooks/{provider}/<sourceId>`. The secret goes into the provider's "shared secret" / "signing secret" / "client secret" field — the exact name varies.
  </Step>

  <Step title="Test delivery">
    Most providers expose a "send test event" or "trigger sample" button. Use it; check the dashboard delivery history for the source. A successful test shows the raw payload + the mapped event.
  </Step>

  <Step title="Map provider events to Notifizz events">
    Each connector ships a default mapping that translates provider event types into the Notifizz grammar (e.g. Stripe's `invoice.payment_succeeded` → `stripe.invoice.paid`). The dashboard exposes a UI for renaming and for marking unmapped types as "ignored".
  </Step>

  <Step title="Wire campaigns">
    Mapped events behave exactly like `client.track()` events — campaigns key on the mapped name. Create a campaign listening on `stripe.invoice.paid` and trigger it from any Stripe webhook delivery.
  </Step>
</Steps>

## Per-provider setup

### Segment

<Steps>
  <Step title="Add a Segment source in Notifizz">
    Dashboard → Sources → Add → Segment. Note the URL and the `verificationSecret`.
  </Step>

  <Step title="Configure Segment">
    In Segment: Destinations → Webhooks → Create. Paste the Notifizz URL. In the destination's settings, find "Shared Secret" and paste the `verificationSecret`.
  </Step>

  <Step title="Map your Segment events">
    Segment events arrive as `track`, `identify`, `page`, `screen`, or `group`. The mapper translates them — the most common pattern is `track` events keep their `event` name, others get a `segment.identify` / `segment.page` prefix. Customise via the dashboard's mapping UI.
  </Step>
</Steps>

**Signature scheme**: header `x-signature`, value is `hex(HMAC-SHA1(verificationSecret, rawBody))`.

### Stripe

<Steps>
  <Step title="Add a Stripe source in Notifizz">
    Dashboard → Sources → Add → Stripe. Note the URL.
  </Step>

  <Step title="Add a webhook endpoint in Stripe">
    Stripe Dashboard → Webhooks → Add endpoint. Paste the Notifizz URL. Pick the events you care about (or "all events" for low-volume accounts). Stripe shows a "Signing secret" — copy it and paste into the Notifizz source's `verificationSecret` field.
  </Step>

  <Step title="Map Stripe events">
    Stripe event types use dotted notation already (`invoice.paid`, `customer.subscription.updated`). The mapper prefixes them with `stripe.` so they don't collide with your own events.
  </Step>
</Steps>

**Signature scheme**: header `stripe-signature` with Stripe's multi-element format (`t=<ts>,v1=<sig>`). Notifizz delegates to Stripe's official verifier — the same logic as `Webhook.constructEvent` in the Stripe SDK.

### HubSpot

<Steps>
  <Step title="Add a HubSpot source in Notifizz">
    Dashboard → Sources → Add → HubSpot. Note the URL.
  </Step>

  <Step title="Set up the HubSpot app webhook">
    HubSpot → Settings → Integrations → Apps → Webhooks → Create subscription. Paste the URL. Use the app's Client Secret as the Notifizz `verificationSecret`.
  </Step>

  <Step title="Subscribe to events">
    HubSpot subscriptions are object-based (`contact.creation`, `deal.propertyChange`, …). The mapper produces `hubspot.contact.created`, `hubspot.deal.updated`, etc.
  </Step>
</Steps>

**Signature scheme**: header `x-hubspot-signature-v2` (with `x-hubspot-signature` fallback), value is `hex(HMAC-SHA256(clientSecret, rawBody))`.

### Intercom

<Steps>
  <Step title="Add an Intercom source in Notifizz">
    Dashboard → Sources → Add → Intercom. Note the URL.
  </Step>

  <Step title="Configure the Intercom webhook">
    Intercom → Settings → Webhooks → New Webhook. Paste the URL. Intercom shows a "Hub Secret" — copy it and paste into the Notifizz source's `verificationSecret`.
  </Step>

  <Step title="Subscribe to topics">
    Intercom topics are conversation-centric (`conversation.user.replied`, `contact.created`, …). The mapper translates them to `intercom.conversation.replied`, `intercom.contact.created`, etc.
  </Step>
</Steps>

**Signature scheme**: header `x-hub-signature`, value is `sha1=<hex(HMAC-SHA1(verificationSecret, rawBody))>` — the same GitHub-style scheme. Note the `sha1=` prefix.

## Debugging signature failures

The dashboard delivery history flags signature failures with a 401 entry. The most common causes:

| Symptom                        | Cause                                       | Fix                                                                                                                           |
| ------------------------------ | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 401 on every delivery          | Wrong `verificationSecret`                  | Re-copy from the provider — most providers regenerate the secret if you click "Show" then leave; copy fresh.                  |
| 401 sporadic                   | Stripe timestamp drift                      | NTP your Notifizz region (rare — Stripe's tolerance is generous).                                                             |
| 401 from a specific event type | Provider sent a non-JSON or pre-parsed body | Notifizz expects raw JSON; if the provider unfortunately re-serialised, the byte mismatch breaks HMAC. Open a support ticket. |
| 404 sourceId                   | Wrong URL                                   | Double-check the path — the `sourceId` must match the dashboard. Easy to mis-paste between environments.                      |

## Mapping events

Each connector ships a default mapping out of the box. The dashboard's mapping UI exposes:

* The list of provider event types observed in delivery history.
* The mapped Notifizz event name (editable).
* An "ignore" toggle for events you don't want propagated.

Renames take effect immediately for new deliveries. Past deliveries keep their original mapping (they're stored on the workflow instance for traceability).

## FAQ

<AccordionGroup>
  <Accordion title="Segment 'invalid signature' — wrong secret or wrong source ID?">
    Both fail with 401, but for different reasons. Wrong `sourceId` produces a 404. Wrong secret produces 401 + signature failure in the log. The dashboard delivery history distinguishes the two — read the entry's reason field.
  </Accordion>

  <Accordion title="Stripe `customer.subscription.updated` — what should I name my Notifizz event?">
    By default the mapper produces `stripe.customer.subscription.updated`. Rename it to whatever your campaigns key on (`subscription.updated`, `billing.subscription_changed`, …). Naming consistency with your direct `client.track()` events makes campaigns easier to wire.
  </Accordion>

  <Accordion title="Drop events I don't care about — how?">
    Mark them as "ignored" in the dashboard mapping UI. Notifizz still verifies the signature (so the provider sees 200 and stops retrying), but the event isn't enqueued for campaigns.
  </Accordion>

  <Accordion title="Pause a connector temporarily?">
    Pause the source from its detail page in the dashboard. Pause persists across deploys. Webhook deliveries still arrive (the provider sees 200), but Notifizz drops them.
  </Accordion>

  <Accordion title="Same Stripe event arrives twice — duplicate?">
    The connector uses the provider's event id as the `idempotencyKey`. A retried delivery from Stripe short-circuits with `{ duplicate: true }`. Genuinely identical events from your end (e.g. user clicks twice) have different event ids and are *not* deduped.
  </Accordion>

  <Accordion title="Multiple sources from the same provider — supported?">
    Yes — each source has its own `sourceId` + `verificationSecret`. You can have, say, two Stripe accounts (production + sandbox) wired to the same Notifizz environment; campaigns can match on event content if they need to differentiate.
  </Accordion>
</AccordionGroup>

## See also

<CardGroup cols={2}>
  <Card title="Connector webhooks reference" icon="plug" href="/docs/sdks/how-to/connector-webhooks">
    Wire format, headers, signature formulas.
  </Card>

  <Card title="Events" icon="bolt" href="/docs/concepts/events">
    The grammar mapped events follow.
  </Card>

  <Card title="Campaigns" icon="diagram-project" href="/docs/concepts/campaigns">
    What runs after a mapped event matches.
  </Card>

  <Card title="Event Tracking" icon="code" href="/docs/sdks/event-tracking/overview">
    The native event format connectors normalise to.
  </Card>
</CardGroup>