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

# Receive and Handle Payment Webhook Events in Nova.Pay

> Configure and handle Nova.Pay webhook events from Pagar.me, Stripe, C6 Bank, FocusNFe, and AWS SNS to keep your integration in sync with payment activity.

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.

<Note>
  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.
</Note>

### 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.

<Note>
  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.
</Note>

### 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.

<Warning>
  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.
</Warning>

### 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:

```bash theme={null}
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.

<Note>
  [ngrok](https://ngrok.com) 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.
</Note>

Tools you can use for local webhook tunnelling:

<CardGroup cols={3}>
  <Card title="ngrok" icon="tunnel" href="https://ngrok.com">
    Industry-standard tunnel with a free tier, inspection dashboard, and replay support.
  </Card>

  <Card title="Stripe CLI" icon="terminal" href="https://stripe.com/docs/stripe-cli">
    Built-in Stripe webhook forwarding with `stripe listen --forward-to localhost:3000`.
  </Card>

  <Card title="Cloudflare Tunnel" icon="cloud" href="https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/">
    Persistent free tunnels with a stable URL using `cloudflared`.
  </Card>
</CardGroup>


## Related topics

- [Webhooks API — Handle Payment Gateway Event Callbacks](/api-reference/webhooks.md)
- [Nova.Pay API: Payments, Checkout & Order Management](/introduction.md)
- [Nova.Pay API Authentication: Keys, Hosts & Webhooks](/authentication.md)
- [Nova.Pay Payment Methods: Credit Card, Pix, and Boleto](/concepts/payment-methods.md)
- [Order Lifecycle and Status Transitions in Nova.Pay](/concepts/orders-lifecycle.md)