Webhooks API — Handle Payment Gateway Event Callbacks

Nova.Pay exposes several webhook receiver endpoints, one per integrated payment gateway. Your gateway sends events to these URLs; Nova.Pay verifies the payload and updates order and payment state accordingly. Each endpoint uses the authentication mechanism required by its respective gateway — ranging from HTTP Basic Auth to cryptographic signature verification.

Webhook Endpoints Overview

The table below summarizes every available webhook receiver, the gateway it serves, and the authentication method it enforces.

Endpoint	Gateway	Auth Method
`POST /webhooks`	Pagar.me	HTTP Basic Auth
`POST /webhooks/nova`	Nova Internal	None
`POST /webhooks/focusnfe`	FocusNFe	HTTP Basic Auth
`POST /webhooks/sns`	AWS SNS	SNS Signature Verification
`POST /webhooks/{company_id}/stripe`	Stripe	`Stripe-Signature` Header
`POST /webhooks/{company_id}/c6_bank`	C6 Bank	HTTP Basic Auth

Endpoint Reference

POST /webhooks — Pagar.me

Receives Pagar.me payment lifecycle events such as transaction status changes and chargebacks. Authentication: HTTP Basic Auth using the per-company Pagar.me webhook credentials stored in Nova.Pay. Payload requirement: The request body must include data.metadata.company_id containing a valid Nova.Pay company ID. Nova.Pay uses this field to look up the matching company and validate the provided credentials. Responses:

Status	Meaning
`200 OK`	Event received and processed successfully.
`401 Unauthorized`	Credentials missing, incorrect, or the company ID was not found.

Dashboard setup: In the Pagar.me Dashboard, register your Nova.Pay webhook URL as:

https://pay.nova.money/api/v1/webhooks

Example request:

curl -X POST https://pay.nova.money/api/v1/webhooks \
  -u "your_username:your_password" \
  -H "Content-Type: application/json" \
  -d '{"type": "transaction.status_changed", "data": {"metadata": {"company_id": 5}}}'

POST /webhooks/nova — Nova Internal

Handles internal Nova.Pay events generated within the platform itself. Authentication: None — this endpoint does not require authentication. Responses:

Status	Meaning
`200 OK`	Event received and processed successfully.

This endpoint is intended for internal Nova.Pay infrastructure use. You do not need to configure it in any external gateway dashboard.

POST /webhooks/focusnfe — FocusNFe

Receives fiscal invoice (NF-e) lifecycle events from the FocusNFe service, such as authorization and cancellation callbacks. Authentication: HTTP Basic Auth using your FocusNFe webhook credentials. Responses:

Status	Meaning
`200 OK`	Event received and processed successfully.
`401 Unauthorized`	Credentials missing or incorrect.

Dashboard setup: In the FocusNFe Dashboard, register your Nova.Pay webhook URL as:

https://pay.nova.money/api/v1/webhooks/focusnfe

POST /webhooks/sns — AWS SNS

Receives messages published to an Amazon SNS topic, such as payment confirmation events routed through AWS infrastructure. Authentication: Nova.Pay automatically verifies the SNS message signature using the AWS SDK. You do not need to pass any credentials in the request headers.

Nova.Pay returns 503 Service Unavailable on processing failure so that AWS SNS automatically retries delivery. Do not treat a 503 response as a permanent error — SNS will retry the event according to your topic’s retry policy.

Responses:

Status	Meaning
`200 OK`	Event received and processed successfully.
`503 Service Unavailable`	Processing error — SNS will retry automatically.

Dashboard setup: In the AWS SNS console, create a subscription for your topic with the protocol set to HTTPS and the endpoint URL set to:

https://pay.nova.money/api/v1/webhooks/sns

Nova.Pay handles SNS subscription confirmation automatically on the first request.

POST /webhooks//stripe — Stripe

Receives Stripe payment events (charges, payment intents, refunds, disputes, etc.) scoped to a specific Nova.Pay company.

company_id

integer

required

The Nova.Pay company ID that owns the Stripe integration. This value is used to look up the company’s Stripe webhook secret for signature verification.

Authentication: Stripe sends a Stripe-Signature header with every webhook request. Nova.Pay verifies this signature against the company’s Stripe webhook secret. Requests with a missing or invalid signature are rejected. Responses:

Status	Meaning
`200 OK`	Event received and processed successfully.
`401 Unauthorized`	Signature missing or verification failed.

Dashboard setup:

Open the Stripe Dashboard

Navigate to dashboard.stripe.com and sign in to the account linked to the company.

Go to Webhooks

In the left sidebar, select Developers → Webhooks, then click Add endpoint.

Enter the endpoint URL

Set the endpoint URL to:

https://pay.nova.money/api/v1/webhooks/{company_id}/stripe

Replace {company_id} with the actual Nova.Pay company ID (for example, 42).

Select events

Choose the Stripe event types you want Nova.Pay to receive (for example, payment_intent.succeeded, charge.refunded).

Copy the webhook secret

After saving the endpoint, Stripe displays a Signing secret (starting with whsec_). Copy this value and store it in your Nova.Pay company’s Stripe webhook secret configuration field.

The webhook signing secret is only shown once in the Stripe Dashboard immediately after endpoint creation. If you lose it, you must regenerate a new secret from the endpoint’s detail page.

POST /webhooks//c6_bank — C6 Bank

Receives payment and PIX events from C6 Bank, scoped to a specific Nova.Pay company.

company_id

integer

required

The Nova.Pay company ID that owns the C6 Bank integration. This value is used to look up the company’s C6 Bank webhook credentials.

Authentication: HTTP Basic Auth using the per-company C6 Bank webhook credentials stored in Nova.Pay. Responses:

Status	Meaning
`200 OK`	Event received and processed successfully.
`401 Unauthorized`	Credentials missing, incorrect, or the company ID was not found.

Dashboard setup: In the C6 Bank developer portal, register your Nova.Pay webhook URL as:

https://pay.nova.money/api/v1/webhooks/{company_id}/c6_bank

Replace {company_id} with the actual Nova.Pay company ID.

Setting Up Webhooks

Use this section as a quick-reference checklist when configuring each gateway to point to Nova.Pay.

Pagar.me

Log in to the Pagar.me Dashboard.
Navigate to Settings → Webhooks and click Add webhook.
Set the URL to https://pay.nova.money/api/v1/webhooks.
In Nova.Pay, store the username and password under the company’s Pagar.me webhook credentials settings. These are the same values Pagar.me will use for Basic Auth.

FocusNFe

Log in to the FocusNFe Dashboard.
Go to Configurações → Webhooks and register the URL https://pay.nova.money/api/v1/webhooks/focusnfe.
In Nova.Pay, store the FocusNFe Basic Auth credentials under the company’s FocusNFe webhook credentials settings.

AWS SNS

Open the Amazon SNS console.
Select your topic and choose Create subscription.
Set Protocol to HTTPS and Endpoint to https://pay.nova.money/api/v1/webhooks/sns.
After creation, SNS sends a subscription confirmation request to Nova.Pay — this is handled automatically.

Make sure the SNS topic’s access policy allows sns:Publish from the AWS service or account that produces the events you want Nova.Pay to receive.

Stripe

Follow the step-by-step instructions in the Stripe endpoint section above. After registering the endpoint in the Stripe Dashboard, copy the Signing secret and save it in the Nova.Pay company settings. Nova.Pay uses this secret to verify every inbound Stripe-Signature header.

C6 Bank

Log in to the C6 Bank developer portal.
Locate the webhook or callback configuration for your integration.
Set the callback URL to https://pay.nova.money/api/v1/webhooks/{company_id}/c6_bank, substituting the correct company ID.
In Nova.Pay, store the C6 Bank Basic Auth credentials under the company’s C6 Bank webhook credentials settings.

Testing Webhooks Locally

When developing locally, your server is not publicly reachable, so gateways cannot deliver events to localhost. Use a tunneling tool to create a temporary public URL that forwards traffic to your local machine.

ngrok is a popular choice. After installing it, run ngrok http 3000 (replace 3000 with your local port) to get a public HTTPS URL.

Example workflow with ngrok:

Start your local Nova.Pay server

Start your local application server on port 3000 (or whichever port your setup uses).

Start a tunnel

ngrok http 3000

ngrok will output a forwarding URL such as https://a1b2c3d4.ngrok.io.

For example, to test the Pagar.me webhook, register:

https://a1b2c3d4.ngrok.io/api/v1/webhooks

in the Pagar.me Dashboard for your test environment.

Trigger a test event

Use the gateway’s built-in test event feature (for example, Stripe’s Send test webhook button) or send a manual request:

curl -X POST https://a1b2c3d4.ngrok.io/api/v1/webhooks \
  -u "your_username:your_password" \
  -H "Content-Type: application/json" \
  -d '{"type": "transaction.status_changed", "data": {"metadata": {"company_id": 5}}}'

Staging environment: For more realistic integration testing, use the Nova.Pay staging server instead of your local machine. All endpoint paths remain the same — simply replace the base URL:

https://staging.pay.nova.money/api/v1/webhooks
https://staging.pay.nova.money/api/v1/webhooks/focusnfe
https://staging.pay.nova.money/api/v1/webhooks/sns
https://staging.pay.nova.money/api/v1/webhooks/{company_id}/stripe
https://staging.pay.nova.money/api/v1/webhooks/{company_id}/c6_bank

Never use production gateway credentials or live payment data when pointing a gateway at the staging server. Always use the gateway’s own sandbox or test-mode credentials.

Checkout

Payments

Management

Webhooks

Webhooks API — Handle Payment Gateway Event Callbacks

Webhook Endpoints Overview

Endpoint Reference

POST /webhooks — Pagar.me

POST /webhooks/nova — Nova Internal

POST /webhooks/focusnfe — FocusNFe

POST /webhooks/sns — AWS SNS

POST /webhooks//stripe — Stripe

POST /webhooks//c6_bank — C6 Bank

Setting Up Webhooks

Pagar.me

FocusNFe

AWS SNS

Stripe

C6 Bank

Testing Webhooks Locally

​Webhook Endpoints Overview

​Endpoint Reference

​POST /webhooks — Pagar.me

​POST /webhooks/nova — Nova Internal

​POST /webhooks/focusnfe — FocusNFe

​POST /webhooks/sns — AWS SNS

​POST /webhooks//stripe — Stripe

​POST /webhooks//c6_bank — C6 Bank

​Setting Up Webhooks

​Pagar.me

​FocusNFe

​AWS SNS

​Stripe

​C6 Bank

​Testing Webhooks Locally

Webhook Endpoints Overview

Endpoint Reference

POST /webhooks — Pagar.me

POST /webhooks/nova — Nova Internal

POST /webhooks/focusnfe — FocusNFe

POST /webhooks/sns — AWS SNS

POST /webhooks//stripe — Stripe

POST /webhooks//c6_bank — C6 Bank

Setting Up Webhooks

Pagar.me

FocusNFe

AWS SNS

Stripe

C6 Bank

Testing Webhooks Locally