Provider webhook
Understand why each connection needs a webhook at the provider and what to register at each one.
The purchase does not end when the buyer clicks pay. A PIX (Brazil's instant payment) is paid minutes later, a card payment may go through a review, and refunds and chargebacks arrive days or weeks later. The provider tells Vipter about each of these changes through a webhook: an address of your connection where it sends the notices.
Each connection has its own webhook. If you have two accounts at the same provider, or a test account and a production one, register a webhook for each connection, in the right environment at the provider.
What comes through the webhook
- PIX paid: the order goes from pending to paid when the provider confirms the payment.
- Card approved later: payments that were under review or pending at the provider.
- Refunds: including the ones made directly in the provider's dashboard.
- Chargebacks and disputes.
- Canceled, expired or declined charges.
Without the webhook, these notices never reach Vipter. The order can stay pending even after it is paid, and refunds or chargebacks do not show in the store or in the integrations that depend on them, such as the member area.
Where the URL is
- Open PaymentsProviders and click the connection.
- The connection card has the Provider webhook section, with the Webhook URL and a copy button. Right above the URL, the card says where to paste the address at that provider.
Right after you create a connection, this section is highlighted with the notice One step left: register this webhook at the provider.
The verification secret
Anyone can send a message to a URL. To accept only the notices that really come from the provider, the payments platform checks each notice with a verification secret. Without the secret, it rejects every notice for that connection.
The card shows where the connection stands:
| The card shows | What it means |
|---|---|
| Verification secret configured. | The secret is saved. The provider's notices are accepted. |
| Without the verification secret the platform rejects this provider's events. Register the URL above at the provider, copy the secret and save it here. | The secret still needs to be saved. Until then, every notice is rejected. |
| This provider signs events with the key you already entered: there is no extra secret to register. | The provider uses the key you already entered. You only need to register the URL. |
What each provider asks for
| Provider | Secret in Vipter | Where it comes from |
|---|---|---|
| Stripe | Webhook signing secret | Stripe generates it when you create the webhook destination. It starts with whsec_. |
| Pagar.me | Webhook username (Basic Auth) and Webhook password (Basic Auth) | You choose them and register the same values in the Pagar.me webhook authentication. |
| Mercado Pago | Webhook secret (signature) | Mercado Pago generates it when you set up the application's notifications. |
| Asaas | Webhook token | You set it when you create the webhook in Asaas, or use the token it generates. 32 to 255 characters, with no spaces. |
| Paystack | None | Paystack signs with the connection's Secret Key. |
The full steps are on each provider's page: Stripe, Pagar.me, Mercado Pago, Asaas and Paystack.
Save or change the secret
- On the connection card, fill in the secret field below the URL.
- Click Save secret. You see the message Webhook secret saved.
To change the secret, do the same with the new value. The secret saved in Vipter and the one at the provider must always match: if you renew it at the provider, save it again in Vipter.
Common problems
-
Without the verification secret the platform rejects this provider's events. Register the URL above at the provider, copy the secret and save it here.
The URL may already be registered at the provider, but the secret was not saved in Vipter. Copy the secret from the provider (or, for Pagar.me and Asaas, the value you chose) and save it on the card.
-
The card shows the secret is set, but orders do not change status
The notices are arriving with a different secret, or not arriving at all. Check that the URL registered at the provider is this connection's, that the webhook was created in the same environment (test or production) and that the secret is the same on both sides.
-
The webhook URL for this connection could not be built. Reload the page or contact support.
Vipter could not build this connection's address. Reload the page. If it keeps happening, contact support.
What to do next
- Review the payment flows to decide which account charges each payment.
- See how payments work to understand the full path of a charge.