Webhooks and suppressions

Connector webhooks are provider-facing webhooks. They are different from the developer webhooks you create with the GenieOS API: provider webhooks arrive from ESPs into GenieOS, then GenieOS normalizes them into the send timeline and your own GenieOS webhook subscriptions.

sequenceDiagram
  participant Provider as Delivery provider
  participant Ingress as GenieOS connector webhook
  participant Normalizer as Event normalizer
  participant Timeline as Send timeline
  participant YourApp as Your webhook subscription

  Provider->>Ingress: delivered, bounced, complained, unsubscribed
  Ingress->>Normalizer: verify signature or token
  Normalizer->>Timeline: persist normalized event
  Normalizer->>YourApp: emit GenieOS webhook event

Normalized event types

Providers do not all expose the same signals. SMTP can confirm handoff but usually cannot provide recipient-level opens, clicks, complaints, or downstream bounces unless the SMTP provider offers a separate webhook API.

Suppression flow

GenieOS checks the workspace suppression list before handing a send to any connector. Provider webhooks can also add suppressions when a recipient unsubscribes, hard bounces, or complains.

flowchart LR
  Recipient[Recipient action] --> Provider[Provider event]
  Provider --> Connector[Connector webhook]
  Connector --> Suppression[GenieOS suppression list]
  Suppression --> Future[Future sends blocked before provider handoff]

Troubleshooting

• If events do not appear in GenieOS, confirm the provider webhook URL, secret, and subscribed event types.
• If sends are blocked unexpectedly, check the recipient in workspace suppressions before rotating connector credentials.
• If provider dashboards show events that GenieOS does not, compare the provider event timestamp with the connector installation time.
• If duplicate provider webhooks arrive, GenieOS deduplicates by provider event ID where the provider supplies one.