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

# Connector Webhook Reference

> Per-provider signature schemes for Segment, Stripe, HubSpot, and Intercom webhooks into Notifizz. Setup, headers, mapping events to campaigns.

# Connector webhooks reference

Notifizz ingests events from external sources via per-provider webhook endpoints. Each connector verifies the provider's signature scheme, normalises the payload to the Notifizz event shape, and feeds it into the same pipeline as direct SDK `track()` calls.

## TL;DR

* Endpoint: `POST /v1/webhooks/{provider}/:sourceId` per provider.
* Each provider has its own header name and HMAC scheme — Notifizz handles them all.
* The connector's `verificationSecret` is per-source and stored in the dashboard.
* Once verified, the payload is mapped to a normalised event and pushed to the same queue as SDK calls.

## Supported providers

| Provider     | Endpoint                               | Header                                              | Algorithm              | Body     |
| ------------ | -------------------------------------- | --------------------------------------------------- | ---------------------- | -------- |
| **Segment**  | `POST /v1/webhooks/segment/:sourceId`  | `x-signature`                                       | HMAC-SHA1 hex          | raw JSON |
| **Stripe**   | `POST /v1/webhooks/stripe/:sourceId`   | `stripe-signature`                                  | Stripe SDK verifier    | raw JSON |
| **HubSpot**  | `POST /v1/webhooks/hubspot/:sourceId`  | `x-hubspot-signature-v2` (or `x-hubspot-signature`) | HMAC-SHA256 hex        | raw JSON |
| **Intercom** | `POST /v1/webhooks/intercom/:sourceId` | `x-hub-signature`                                   | `sha1=<HMAC-SHA1 hex>` | raw JSON |

Notifizz handles signature verification per provider, with Stripe's multi-element format delegated to its official verifier semantics.

## Setup flow

<Steps>
  <Step title="Add a source in the dashboard">
    Pick the provider, name the source. Notifizz mints a `sourceId` and a `verificationSecret`. The pair is what the webhook URL and the signature use.
  </Step>

  <Step title="Configure the webhook on the provider">
    Each provider has its own admin UI:

    * **Segment** — Destinations → Webhooks → paste `https://eu.api.notifizz.com/v1/webhooks/segment/<sourceId>`, paste the `verificationSecret` as the shared secret.
    * **Stripe** — Webhooks → Add endpoint → paste the URL, copy the Stripe signing secret back into the dashboard's source.
    * **HubSpot** — Settings → Integrations → Webhooks → paste the URL, copy the app's Client Secret back into the dashboard.
    * **Intercom** — Settings → Webhooks → paste the URL, copy the Hub Secret back into the dashboard.
  </Step>

  <Step title="Map provider events to Notifizz events">
    Each connector ships a default mapping that translates the provider's event names into the Notifizz event grammar. The dashboard surfaces unmapped event types so you can wire them up explicitly.
  </Step>

  <Step title="Wire campaigns to the mapped events">
    From the campaign side, mapped events are first-class — your campaign listens on `stripe.invoice.paid` (or whatever name your mapper produces) the same way it listens on `client.track()` events.
  </Step>
</Steps>

## Per-provider signature details

### Segment

```
signature = hex(HMAC-SHA1(verificationSecret, rawBody))
```

Header: `x-signature`. Direct hex comparison. See.

### Stripe

Stripe's signature format includes a timestamp and an HMAC, separated by commas — `t=<ts>,v1=<sig>`. The Notifizz verifier delegates to Stripe's SDK `Webhook.constructEvent` semantics via a dedicated port — no `apiKey` is required for verification; the secret alone is enough.

Header: `stripe-signature`.

### HubSpot

```
signature = hex(HMAC-SHA256(verificationSecret, rawBody))
```

Header: `x-hubspot-signature-v2`, with a `x-hubspot-signature` fallback. See.

### Intercom

```
signature = "sha1=" + hex(HMAC-SHA1(verificationSecret, rawBody))
```

Header: `x-hub-signature` (the same scheme as GitHub-style webhooks — note the `sha1=` prefix). See.

## Normalised event shape

After verification, each connector's event-mapper produces a standard Notifizz event:

```json theme={null}
{
  "eventName": "stripe.invoice.paid",
  "properties": { /* provider payload, normalised */ },
  "sdkSecretKey": "<resolved from sourceId>",
  "idempotencyKey": "<provider-event-id>"
}
```

The `idempotencyKey` is derived from the provider's event id so re-deliveries from the provider naturally dedupe.

## FAQ

<AccordionGroup>
  <Accordion title="Signature invalid — wrong secret or wrong source id?">
    Both produce a 401. Most common cause: the `verificationSecret` in the dashboard doesn't match the one configured on the provider. Less common: the URL `:sourceId` segment is wrong (typo or wrong env). Check the request log — the failed verification is logged with which check failed.
  </Accordion>

  <Accordion title="Stripe event arrived but no campaign fired — why?">
    The event was accepted (signature OK), but no campaign listens on the mapped event name. Either: (1) the connector's mapping hasn't named this event type yet (check the dashboard's "unmapped events" view), or (2) no campaign is wired to the mapped name. The dashboard delivery history shows the event with a no-route entry.
  </Accordion>

  <Accordion title="How do I rename a Stripe `invoice.paid` to my own name?">
    The mapping happens in the connector. The dashboard exposes a UI for renaming mapped events without touching code — the rename takes effect immediately for new webhook deliveries.
  </Accordion>

  <Accordion title="Disable a connector temporarily — how?">
    Pause it from the source detail page in the dashboard. Pause persists across deploys. Webhook deliveries still arrive, but they're rejected with a 200 + paused flag — the provider sees success and stops retrying, but Notifizz drops them.
  </Accordion>

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

  <Accordion title="Multiple sources from the same provider in one environment — supported?">
    Yes — each source has its own `sourceId` and `verificationSecret`. You can have, say, two Stripe accounts 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="Event Tracking" icon="code" href="/docs/sdks/event-tracking/overview">
    The native event format that connectors normalise to.
  </Card>

  <Card title="Integrations guide" icon="plug" href="/docs/sdks/how-to/integrations">
    Customer-facing setup walkthrough per provider.
  </Card>

  <Card title="Error catalogue" icon="circle-exclamation" href="/docs/sdks/error-catalogue">
    Webhook verification error codes.
  </Card>

  <Card title="How Notifizz works" icon="diagram-project" href="/docs/concepts/how-it-works">
    Where connector events join the pipeline.
  </Card>
</CardGroup>