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

# Webhooks API — Handle Payment Gateway Event Callbacks

> Nova.Pay webhook endpoints receive events from Pagar.me, Stripe, C6 Bank, FocusNFe, and AWS SNS. Each endpoint authenticates and processes events.

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:

```text theme={null}
https://pay.nova.money/api/v1/webhooks
```

**Example request:**

<CodeGroup>
  ```bash cURL theme={null}
  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}}}'
  ```
</CodeGroup>

***

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

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

***

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

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

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

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

```text theme={null}
https://pay.nova.money/api/v1/webhooks/sns
```

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

***

### POST /webhooks/{company_id}/stripe — Stripe

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

<ParamField path="company_id" type="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.
</ParamField>

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

<Steps>
  <Step title="Open the Stripe Dashboard">
    Navigate to [dashboard.stripe.com](https://dashboard.stripe.com) and sign in to the account linked to the company.
  </Step>

  <Step title="Go to Webhooks">
    In the left sidebar, select **Developers → Webhooks**, then click **Add endpoint**.
  </Step>

  <Step title="Enter the endpoint URL">
    Set the endpoint URL to:

    ```text theme={null}
    https://pay.nova.money/api/v1/webhooks/{company_id}/stripe
    ```

    Replace `{company_id}` with the actual Nova.Pay company ID (for example, `42`).
  </Step>

  <Step title="Select events">
    Choose the Stripe event types you want Nova.Pay to receive (for example, `payment_intent.succeeded`, `charge.refunded`).
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

***

### POST /webhooks/{company_id}/c6\_bank — C6 Bank

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

<ParamField path="company_id" type="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.
</ParamField>

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

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

1. Log in to the [Pagar.me Dashboard](https://dashboard.pagar.me).
2. Navigate to **Settings → Webhooks** and click **Add webhook**.
3. Set the URL to `https://pay.nova.money/api/v1/webhooks`.
4. 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

1. Log in to the [FocusNFe Dashboard](https://focusnfe.com.br).
2. Go to **Configurações → Webhooks** and register the URL `https://pay.nova.money/api/v1/webhooks/focusnfe`.
3. In Nova.Pay, store the FocusNFe Basic Auth credentials under the company's **FocusNFe webhook credentials** settings.

### AWS SNS

1. Open the [Amazon SNS console](https://console.aws.amazon.com/sns).
2. Select your topic and choose **Create subscription**.
3. Set **Protocol** to `HTTPS` and **Endpoint** to `https://pay.nova.money/api/v1/webhooks/sns`.
4. After creation, SNS sends a subscription confirmation request to Nova.Pay — this is handled automatically.

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

### Stripe

Follow the step-by-step instructions in the [Stripe endpoint section](#post-webhooks-company_id-stripe) 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

1. Log in to the C6 Bank developer portal.
2. Locate the webhook or callback configuration for your integration.
3. Set the callback URL to `https://pay.nova.money/api/v1/webhooks/{company_id}/c6_bank`, substituting the correct company ID.
4. 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.

<Tip>
  [ngrok](https://ngrok.com) is a popular choice. After installing it, run `ngrok http 3000` (replace `3000` with your local port) to get a public HTTPS URL.
</Tip>

**Example workflow with ngrok:**

<Steps>
  <Step title="Start your local Nova.Pay server">
    Start your local application server on port 3000 (or whichever port your setup uses).
  </Step>

  <Step title="Start a tunnel">
    ```bash theme={null}
    ngrok http 3000
    ```

    ngrok will output a forwarding URL such as `https://a1b2c3d4.ngrok.io`.
  </Step>

  <Step title="Register the tunnel URL in your gateway dashboard">
    For example, to test the Pagar.me webhook, register:

    ```text theme={null}
    https://a1b2c3d4.ngrok.io/api/v1/webhooks
    ```

    in the Pagar.me Dashboard for your test environment.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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}}}'
    ```
  </Step>
</Steps>

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

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

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


## Related topics

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