Handle Paystack Webhooks in Vue

Webhooks are HTTP POST requests that Paystack sends from its servers to a URL on your server. The destination is a backend endpoint like https://api.yourapp.com/webhooks/paystack. That endpoint must be a running server process that can accept incoming HTTP connections over HTTPS.

Vue is a frontend JavaScript framework. It renders components in the user's browser. A browser cannot accept incoming HTTP connections from Paystack's servers. There is no port to listen on, no public URL to register, and no way for Paystack to reach a user's browser even if there were.

This applies to Vue 2, Vue 3, and any Vue-based SPA. It also applies to every other frontend-only framework: React, Angular, Svelte (without SvelteKit). Webhooks are strictly a backend concern.

If you want to handle webhooks within the Vue ecosystem, the answer is Nuxt. Nuxt is the full-stack framework for Vue, and it provides server routes that can receive webhook POST requests. See Handle Paystack Webhooks in Nuxt.

Here is how a Paystack integration works when your frontend is a Vue SPA:

1. Vue (frontend): Opens the Paystack checkout popup. The customer enters payment details and completes the transaction.
2. Paystack: Processes the payment and sends a webhook POST to your backend server.
3. Your backend: Receives the webhook, verifies the x-paystack-signature header with HMAC SHA512, processes the event, and updates the database.
4. Vue (frontend): Polls your backend API or uses a real-time connection to check the payment status and update the UI.

Customer Browser (Vue SPA)
    |
    | 1. Opens Paystack Popup, customer pays
    v
Paystack Servers
    |
    | 2. Sends webhook POST to your backend
    v
Your Backend (Express, Django, Laravel, etc.)
    |
    | 3. Verifies signature, processes event, updates DB
    v
Database
    ^
    | 4. Vue app fetches updated state via API
    |
Customer Browser (Vue SPA)

The Vue app and the webhook handler live in completely separate worlds. The Vue app talks to your backend via REST or GraphQL APIs. The webhook handler talks to Paystack and your database. They share the database, but that is the only connection.

When a customer finishes paying through the Paystack popup, your Vue app receives a callback with the transaction reference. Use this for immediate UI feedback, but do not treat it as the final confirmation.

// Vue 3 Composition API example
import { ref } from 'vue';

const paymentStatus = ref('idle');

function onPaymentSuccess(response: { reference: string }) {
  paymentStatus.value = 'verifying';
  pollPaymentStatus(response.reference);
}

async function pollPaymentStatus(reference: string) {
  try {
    const res = await fetch('/api/orders/status?ref=' + reference);
    const data = await res.json();

    if (data.status === 'paid') {
      paymentStatus.value = 'confirmed';
      // Navigate to success page or update UI
    } else {
      // Webhook has not been processed yet, try again
      setTimeout(function() { pollPaymentStatus(reference); }, 2000);
    }
  } catch (err) {
    paymentStatus.value = 'error';
  }
}

The Vue app asks your backend: "Has the webhook confirmed this payment?" It does not verify the payment itself. It does not call the Paystack API directly (that would expose your secret key). It simply checks what your backend already knows.

You need a backend to handle Paystack webhooks. Here are guides for every major framework:

Full-stack Vue (recommended if you are in the Vue ecosystem):

• Nuxt provides server routes in the same project as your Vue frontend

Node.js:

• Node.js and Express
• NestJS

Python:

• Django
• FastAPI
• Flask

PHP:

• Laravel
• Symfony

Other:

• Go
• Ruby on Rails
• Spring Boot (Java)
• ASP.NET Core (C#)

Serverless:

• Supabase Edge Functions
• Firebase Cloud Functions

If you are a Vue developer and do not want to learn a new framework, Nuxt is the natural choice. It gives you server routes where you can write webhook handlers in the same project as your Vue components.

Nuxt is to Vue what Next.js is to React. It adds server-side rendering, server routes, and API endpoints to your Vue project. If you want to handle Paystack webhooks without setting up a separate backend, Nuxt is the way to go.

In Nuxt, you create a server route at server/api/webhooks/paystack.post.ts. The .post suffix restricts it to POST requests only. Inside, you read the raw body, verify the HMAC SHA512 signature, and process the event. Your Vue components and your webhook handler live in the same project and share the same deployment.

See Handle Paystack Webhooks in Nuxt for the full implementation.

1. Trying to "listen" for webhooks in the Vue app. There is no way to set up an HTTP listener in a browser. Webhooks go to a server.

2. Exposing the Paystack secret key in Vue. Environment variables prefixed with VITE_ are bundled into the client-side code and visible in the browser. Your Paystack secret key must never start with VITE_. Keep it on the server only.

3. Calling the Paystack Verify API from the frontend. This requires your secret key in the Authorization header. If you make this call from Vue, you expose the key. Always call the Verify API from your backend.

4. Treating the popup callback as final confirmation. The callback runs in the browser and can be faked, skipped, or missed. The webhook is the reliable source of truth. Your backend should update the order via webhook, and your Vue frontend should check the backend for the final status.

5. Not handling the race condition. Sometimes the webhook arrives at your backend before the customer is redirected back to your Vue app. When your Vue app loads the success page, it should check the payment status from your backend, not assume the webhook has not arrived yet. See race conditions between webhooks and redirect callbacks.

This guide is part of the Paystack integration guides by language and framework series.