Introduction

Webhooks are HTTP callbacks that deliver Swervpay event notifications to your application. When an event occurs, Swervpay sends an HTTP POST request to the configured URL. Your endpoint should verify the delivery, enqueue or process it idempotently, and respond with a 2xx status code promptly. You can subscribe to card, collection, customer, payout, wallet, and bill events. See the resource-specific pages for payload examples and event behavior.

Creating a Webhook

You can create a webhook from the dashboard or with the create webhook API. Use the edit webhook API to change its URL, description, or subscribed events.

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. You can inspect delivery status and response details with the webhook logs 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