Back to Guides
Security & Integration

Handling Webhooks

Learn how to securely listen for verification events and update your database when a user completes the KYC process.

Webhooks allow Spidify to send real-time HTTP POST payloads to your server when events happen in your account. This is particularly useful for asynchronous events like identity verification completion.

Step 1: Set up your endpoint

Create a public route on your server that can receive POST requests. This endpoint will be where Spidify sends the event data.

app.post('/webhooks/spidify', (req, res) => {
  const event = req.body;

  // Handle the event
  switch (event.event) {
    case 'verification.completed':
      const verificationData = event.data;
      console.log(`Verification ${verificationData.reference} was ${verificationData.status}`);
      
      // Update your database
      updateUserVerificationStatus(verificationData.reference, verificationData.status);
      break;
      
    default:
      console.log(`Unhandled event type ${event.event}`);
  }

  // Return a 200 response to acknowledge receipt
  res.json({ received: true });
});

Step 2: Configure Webhook URL in Dashboard

Once your endpoint is ready, go to the Developer Settings in your Spidify Dashboard and add your webhook URL.

Note: For local testing, use a tool like ngrok to expose your local server to the internet.

Step 3: Handle the Event Payload

Spidify sends events as JSON in the request body. The most important event to handle is verification.completed.

{
  "event": "verification.completed",
  "data": {
    "reference": "SP_REV_8231...",
    "status": "APPROVED",
    "user_details": {
      "fullName": "John Doe",
      "nin": "1234567890"
    }
  }
}

Always return a 200 OK response quickly to acknowledge receipt of the webhook. Do not perform long-running tasks before responding, as Spidify may timeout and retry sending the event.