Receive and Handle Payment Webhook Events in Nova.Pay

Nova.Pay forwards payment gateway events to your system via dedicated webhook receiver endpoints. Each gateway has its own URL and authentication scheme, so your integration stays in sync with the underlying payment processors without polling the API. This guide covers every available endpoint, how authentication works for each, and practical tips for testing your webhook handlers locally.

Available Webhook Endpoints

Register these URLs in your gateway dashboard or Nova.Pay configuration, pointing to your Nova.Pay deployment’s base URL (https://pay.nova.money/api/v1).

Endpoint	Gateway	Authentication
`POST /webhooks`	Pagar.me	HTTP Basic Auth; `data.metadata.company_id` required in payload
`POST /webhooks/nova`	Nova.Pay platform events	None
`POST /webhooks/focusnfe`	FocusNFe	HTTP Basic Auth
`POST /webhooks/sns`	AWS SNS	AWS signature verification
`POST /webhooks/{company_id}/stripe`	Stripe	Webhook secret (`Stripe-Signature` header)
`POST /webhooks/{company_id}/c6_bank`	C6 Bank	HTTP Basic Auth

Replace {company_id} with your Nova.Pay company identifier when registering Stripe or C6 Bank webhooks.

Authentication Per Gateway

Pagar.me and FocusNFe

Both Pagar.me and FocusNFe endpoints use HTTP Basic Auth. Configure the credentials in your Nova.Pay dashboard and supply matching credentials when registering the webhook URL in the respective gateway portal.

For Pagar.me, the incoming event payload must include a valid data.metadata.company_id value. Requests that are missing this field or contain an unrecognised company ID will be rejected.

Stripe

Stripe webhook events are authenticated using a webhook secret. Nova.Pay verifies the Stripe-Signature header on every incoming request using the secret you configure.

Register your Nova.Pay webhook URL in the Stripe Dashboard under Developers → Webhooks, and copy the generated signing secret into your Nova.Pay configuration. The Stripe-Signature header must be present on every request or it will be rejected.

AWS SNS

SNS events are authenticated via AWS signature verification using the AWS SDK. Nova.Pay validates the authenticity of each SNS notification before processing it.

If Nova.Pay cannot process an SNS notification and returns HTTP 503, SNS will automatically retry the delivery according to its retry policy. This is intentional — design your SNS event handler to be idempotent so that duplicate deliveries do not cause unintended side effects.

C6 Bank

C6 Bank events are authenticated using HTTP Basic Auth, following the same pattern as Pagar.me and FocusNFe.

Registering a Stripe Webhook

Use the Stripe CLI or the following curl command to register your Nova.Pay endpoint as a Stripe webhook destination:

curl -X POST "https://api.stripe.com/v1/webhook_endpoints" \
  -u "sk_live_YOUR_STRIPE_SECRET_KEY:" \
  -d "url=https://pay.nova.money/api/v1/webhooks/YOUR_COMPANY_ID/stripe" \
  -d "enabled_events[]=payment_intent.succeeded" \
  -d "enabled_events[]=payment_intent.payment_failed" \
  -d "enabled_events[]=charge.refunded"

Stripe will respond with a webhook_endpoint object that includes the secret field — copy this value into your Nova.Pay Stripe configuration.

Testing Webhooks Locally

Gateway providers cannot reach localhost directly. During development, use a tunnelling tool to expose your local server to the internet and use the resulting public URL when registering the webhook.

ngrok is a popular choice for local webhook testing. Run ngrok http 3000 (replacing 3000 with your local port) to get a public HTTPS URL, then register that URL in your gateway dashboard. Remember to update the URL every time ngrok restarts unless you have a paid plan with a reserved domain.

Tools you can use for local webhook tunnelling:

ngrok

Industry-standard tunnel with a free tier, inspection dashboard, and replay support.

Stripe CLI

Built-in Stripe webhook forwarding with stripe listen --forward-to localhost:3000.

Cloudflare Tunnel

Persistent free tunnels with a stable URL using cloudflared.

Get Started

Concepts

Guides

Receive and Handle Payment Webhook Events in Nova.Pay

Available Webhook Endpoints

Authentication Per Gateway

Pagar.me and FocusNFe

Stripe

AWS SNS

C6 Bank

Registering a Stripe Webhook

Testing Webhooks Locally

ngrok

Stripe CLI

Cloudflare Tunnel

​Available Webhook Endpoints

​Authentication Per Gateway

​Pagar.me and FocusNFe

​Stripe

​AWS SNS

​C6 Bank

​Registering a Stripe Webhook

​Testing Webhooks Locally

ngrok

Stripe CLI

Cloudflare Tunnel

Available Webhook Endpoints

Authentication Per Gateway

Pagar.me and FocusNFe

Stripe

AWS SNS

C6 Bank

Registering a Stripe Webhook

Testing Webhooks Locally