Introduction

Webhooks are a way for Swervpay to provide real-time data to your application. They are HTTP callbacks that receive notification messages for events. When an event occurs, Swervpay sends an HTTP POST request to the webhook’s configured URL. Your endpoint should respond with a 2xx status code to indicate that the event has been successfully received.

Creating a Webhook

You can create a webhook from the dashboard.

Contactless activation subscriptions

Contactless activation codes are confidential and are not sent to a webhook by default. To receive them, explicitly subscribe one enabled HTTPS webhook to card.contactless.activation. Create a subscribed webhook:

curl --request POST \
  --url https://api.swervpay.co/api/v1/webhook \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/webhooks/swervpay",
    "description": "Contactless activation webhook",
    "events": ["card.contactless.activation"]
  }'

Or update an existing webhook:

curl --request PUT \
  --url https://api.swervpay.co/api/v1/webhook/<WEBHOOK_ID> \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/webhooks/swervpay",
    "description": "Contactless activation webhook",
    "events": ["card.contactless.activation"]
  }'

The endpoint must:

Use HTTPS.
Return a 2xx response.
Be the only enabled webhook subscribed to card.contactless.activation for the business.

When no unique eligible subscription can be resolved, or delivery fails, Swervpay sends the activation code using the standard Swervpay email instead.

Supplying events when editing replaces the webhook’s stored event list. Include every event that should remain explicitly registered. Omitting events preserves the existing list.

Authentication

All webhook requests include a X-SWERV-SECRET header for verification. It should match the secret generated when creating the webhook. The confidential card.contactless.activation event uses an HMAC signature instead of X-SWERV-SECRET. See the card webhook documentation for its headers and verification procedure.

const secret = process.env.SWERVPAY_SECRET;

function verifyWebhook(req, res, next) {
  if (req.headers['X-SWERV-SECRET'] !== secret) {
    return res.status(401).json({
      message: "Unauthorized request."
    });
  }
  next();
}

router.post('/webhook', verifyWebhook, (req, res) => {
  const webhook = req.body;
  switch(webhook.event) {
    case "card.created":
  
    break;
  }
  return res.sendStatus(200);
});

$secret = getenv('SWERVPAY_SECRET');

function verifyWebhook($secret) {
    $header = $_SERVER['HTTP_SWERVPAY_SECRET'];
    if ($header !== $secret) {
        http_response_code(401);
        echo 'Unauthorized request';
        exit();
    }
}

function handleWebhook() {
    $json = file_get_contents('php://input');
    $data = json_decode($json, true);

    if (json_last_error() !== JSON_ERROR_NONE) {
        http_response_code(400);
        echo 'Invalid JSON body';
        exit();
    }

    switch ($data['event']) {
        case 'card.created':
            // Handle the event
            break;
    }

    http_response_code(200);
}

verifyWebhook($secret);
handleWebhook();

// In your middleware
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class VerifyWebhook
{
    public function handle(Request $request, Closure $next)
    {
        $secret = env('SWERVPAY_SECRET');
        if ($request->header('X-SWERV-SECRET') !== $secret) {
            return response('Unauthorized request', 401);
        }

        return $next($request);
    }
}

// In your controller
namespace App\Http\Controllers;

use Illuminate\Http\Request;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        $data = $request->json()->all();

        switch ($data['event']) {
            case 'card.created':
                // Handle the event
                break;
        }

        return response(null, 200);
    }
}

// In your routes/web.php or routes/api.php
Route::post('/webhook', 'App\Http\Controllers\WebhookController@handle')->middleware('App\Http\Middleware\VerifyWebhook');

package main

import (
    "encoding/json"
    "net/http"
    "os"

    "github.com/gorilla/mux"
)

var secret = os.Getenv("SWERVPAY_SECRET")

func verifyWebhook(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.Header.Get("X-SWERV-SECRET") != secret {
            http.Error(w, "Unauthorized request", http.StatusUnauthorized)
            return
        }
        next.ServeHTTP(w, r)
    })
}

type Webhook struct {
    Event string `json:"event"`
}

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    var webhook Webhook
    err := json.NewDecoder(r.Body).Decode(&webhook)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    switch webhook.Event {
    case "card.created":
        // Handle the event
    }

    w.WriteHeader(http.StatusOK)
}

func main() {
    r := mux.NewRouter()
    r.Use(verifyWebhook)
    r.HandleFunc("/webhook", handleWebhook).Methods("POST")
    http.ListenAndServe(":8080", r)
}

Retry

If a webhook fails, you have two main options to retry the failed delivery:

Retry from developer section of the dashboard
Using webhook Retry API

Get Started

Wallet

Transaction

Customer

Card

Collection

FX

Payout

Webhook Events

Introduction

Introduction

Creating a Webhook

Contactless activation subscriptions

Authentication

Retry

​Introduction

​Creating a Webhook

​Contactless activation subscriptions

​Authentication

​Retry

Introduction

Creating a Webhook

Contactless activation subscriptions

Authentication

Retry