Documentation/Integrations/Webhooks & Events

Webhooks & Events

How external systems push events into Supero — payment and messaging provider callbacks through the managed services catalog, and inbound triggers for your own connectors. Read the verification table before you rely on a callback: signature checking is built in for four providers, not for the whole catalog.

Overview

A webhook, here, means an external system delivering an HTTP POST into Supero — not Supero polling out. Two real, independent mechanisms use this pattern, and this page covers both: a managed integration (Stripe, Razorpay, PhonePe, GitHub, Slack, and others) confirming an event against a service you imported from the catalog, and an inbound trigger that kicks off a run of one of your own connectors.

If what you actually want is the reverse direction — Supero calling out to an endpoint you control — that is the Plugin Registry, not a webhook. And if you want something to happen automatically whenever a record in your own app is created, updated, or deleted, that is an event binding on a workflow, which runs entirely inside Supero with no external HTTP call at all.

You want to…	Use	See
Receive a payment/message provider's callback for a service you imported	The service's own inbound webhook (this page)	Inbound Webhooks from Managed Integrations
Trigger one of your own connectors from an external push (GitHub, Shopify, a generic HMAC sender…)	A connector with trigger.type "webhook" (this page)	Inbound Webhooks for Connectors
Have Supero call an HTTP endpoint you own, on demand	The Plugin Registry	Plugin Registry page
Fire an automated flow when your own data changes	A workflow event binding (@create/@update/@delete)	Workflows & Automation page

Inbound Webhooks from Managed Integrations

Several catalog services are two-way: you call them through /api/v1/services/execute, and the provider calls you back to confirm what happened — a checkout session completing, a payment settling, an issue being commented on. Once you import and configure one of these services, its provider-facing webhook endpoint is live automatically; you only need to paste the URL into that provider's dashboard and, where applicable, set the matching signing secret in the service's config.

service_id	Provider	What the callback confirms
stripe_checkout	Stripe	Hosted checkout session completed or a delayed payment method settled
billing	Stripe	Subscription and invoice lifecycle events for your own Stripe billing integration
billing_razorpay	Razorpay	Payment link, order, or payment captured
billing_phonepe	PhonePe	Checkout order completed or failed, refund completed or failed
billing_paypal	PayPal	Order and payment lifecycle events
github	GitHub	Repository events (issues, pull requests, pushes) for your imported GitHub integration
slack	Slack	Slack event subscriptions for your imported Slack integration

Import and configure the service the same way you would for any catalog integration, then find the exact webhook URL to give the provider on that service's configuration screen in the dashboard.

bash

# Import stripe_checkout into the current project
curl -X POST https://api.supero.dev/api/v1/services/import \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service_id": "stripe_checkout"}'

# Set the webhook signing secret Stripe gives you when you create the
# endpoint in the Stripe Dashboard
curl -X PUT https://api.supero.dev/api/v1/services/stripe_checkout/config \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stripe_webhook_secret": "whsec_..."}'

service_id	Config field for the webhook secret
stripe_checkout / billing	stripe_webhook_secret
billing_razorpay	razorpay_webhook_secret
billing_phonepe	phonepe_webhook_username and phonepe_webhook_password (PhonePe signs with SHA-256 of username:password, not HMAC)

🚨 Signature verification covers four providers — not every provider in the catalog

This is the most important sentence on this page, so it is stated exactly. Supero has hardcoded inbound signature verification for four providers only: Stripe, Razorpay, PayPal and PhonePe. For those four, an unsigned or badly-signed event is rejected, and Stripe and PayPal additionally return 503 rather than proceeding when their secret is unset — they fail closed. Every other provider callback, including GitHub and Slack, is dispatched without signature verification.

🚨 Some providers collect a signing secret that nothing reads

Slack (slack_signing_secret) and SendGrid (sendgrid_webhook_signing_key) both present a signing-secret field in their configuration, and no code path consults either value. GitHub declares its inbound endpoint with no secret field at all. Setting these fields does not make those callbacks verified. If you are exposing a GitHub, Slack or SendGrid callback on the public internet, treat the payload as unauthenticated input and verify it yourself, or gate the action it triggers on something you can check independently.

Provider	Inbound signature verified?	Behaviour when the secret is unset
Stripe	Yes — HMAC	Fails closed (503)
PayPal	Yes — verified against PayPal	Fails closed (503)
Razorpay	Yes — HMAC	Rejected
PhonePe	Yes — SHA-256 of username:password	Rejected
GitHub	No	No secret is consulted; the event is dispatched
Slack	No — the field exists but is unread	No secret is consulted; the event is dispatched
SendGrid	No — the field exists but is unread	No secret is consulted; the event is dispatched
Everything else in the catalog	No	Dispatched unverified

⚠️ A verified webhook is not a confirmed payment

For the four verified providers, what is checked is the signature — that the message came from the provider and was not altered. The event body is not re-fetched against the provider's status API before being acted on. A verified Stripe event carries an amount bound by a read-before-write check, which is a narrower guarantee than "the payment is confirmed with Stripe". If your flow needs authoritative confirmation, query the provider yourself before releasing goods or credit.

Inbound Webhooks for Connectors

A connector normally runs on a schedule or a manual trigger. Set its trigger to type "webhook" instead, and an external POST to a per-connector URL starts a run — useful for a source that only tells you when something changed (a Shopify order, a GitHub push) rather than one you poll.

http

POST https://api.supero.dev/api/v1/webhooks/{domain}/{connector_id}

trigger field	Purpose
type	Set to "webhook" to accept inbound events instead of running on a schedule.
webhook_secret	Shared secret used to verify the sender's signature. Omit it and Supero accepts any request to that URL without verification — set it before pointing a real provider at the endpoint.
webhook_events	Optional allow-list of event-type strings. When set, an event whose type is not in the list is acknowledged (200) but skipped rather than triggering a run.
allow_manual	Whether POST /api/v1/connectors/{connector_id}/run is also allowed alongside webhook triggers. Defaults to true.

The connector must also be enabled — a disabled connector acknowledges the webhook with a 200 but does not run.

Create it with the Python SDK

python

import supero

org = supero.connect(domain_name="acme-corp", api_key="ak_...")

connector = org.connectors.connect_api(
    name="shopify-order-events",
    base_url="https://your-shop.myshopify.com",
    endpoint="/admin/api/2024-01/orders.json",
    trigger={
        "type": "webhook",
        "webhook_secret": "your-shared-secret",
        "webhook_events": ["orders/create", "orders/updated"],
    },
)

org.connectors.enable(connector["uuid"])
print(connector["uuid"])  # use this as {connector_id} in the webhook URL above

org.connectors.plugins() lists the available source plugins (database, http_api, csv_file, webhook) if you want to see what create()/connect_api()/connect_database() can target. See the Connectors Overview page for the full set of source configs, including a "webhook" source plugin where the pushed payload itself becomes the record — rather than the webhook simply kicking off a fresh pull of another source.

How Signatures Are Checked

The connector webhook endpoint auto-detects the sender from the request headers and verifies against connector.trigger.webhook_secret before triggering anything. Nothing on your side needs to compute a signature — the sender (Stripe, GitHub, etc.) signs the request the same way it always does; Supero verifies it on receipt.

Sender	Signature header	Scheme
Stripe	Stripe-Signature	t=<timestamp>,v1=<hex hmac-sha256> over "<timestamp>.<body>"; rejected if the timestamp is more than 5 minutes old
GitHub	X-Hub-Signature-256	sha256=<hex hmac-sha256> over the raw body
Shopify	X-Shopify-Hmac-SHA256	base64 hmac-sha256 over the raw body
Slack	X-Slack-Signature	v0=<hex hmac-sha256> over "v0:<timestamp>:<body>", with X-Slack-Request-Timestamp
Anything else	X-Webhook-Signature (or X-Signature)	hex hmac-sha256 over the raw body, optionally prefixed sha256=

💡 A failed run beats a silent skip

A request whose signature does not verify is rejected with 401 rather than silently ignored, so a misconfigured secret shows up immediately as failed deliveries in the sending provider's dashboard instead of as data that quietly never arrives.

A request that carries no recognized signature header and no webhook_secret configured is accepted unverified — that is only appropriate while you are wiring things up. For anything reachable from the public internet, set webhook_secret before you rely on the connector.

Plan Availability

Connectors — and so webhook-triggered connector runs — are part of the connectors feature, available from the Basic plan up; the Trial plan does not include connectors. Broader integrations capability (multiple backends, priority support alongside the catalog) is bundled from Pro and up. Each connector run, however it was triggered, draws from your plan's Power usage allowance. Current plan names, included allowances, and prices are on the Billing screen in your dashboard at app.supero.dev/billing and are subject to change.

Plan (plan_code)	Connectors incl. webhook triggers
Trial (trial)	Not included
Basic (basic)	Included
Starter (starter)	Included
Pro (pro)	Included
Business (business)	Included
Enterprise (enterprise)	Included

Next Steps

•Connectors Overview — source types, data modes, and the full connector lifecycle that webhook triggers fit into
•API Integrations — the managed services catalog, importing and configuring the services that send these callbacks
•Plugin Registry — the reverse direction: register your own endpoint and have Supero call it
•Workflows & Automation — fire an automated flow when your own data changes, with no external HTTP call involved

← PreviousAPI Integrations Next →Managed Integrations & Provider Catalog

On this page