Receiving and verifying webhooks

We send an event to your endpoint every time a payment, refund or payout changes status. Events are signed the Standard Webhooks way, so you verify them with a ready library — no signing code of your own.

1. Set the endpoint

One HTTPS endpoint per project: a named public host, port 443 or 8443. An IP address, another port, a username in the URL or a fragment is 422 url_not_allowed.

curl

examples/curl/webhooks/endpoint/set.sh

#!/usr/bin/env bash
# Point events at your HTTPS address. Keep the secret of the first answer: it is shown once.
set -euo pipefail
. "$(dirname "$0")/../../signed-request.sh"

body=$(cat <<JSON
{
  "url": "${WEBHOOK_URL:-https://shop.example.lk/webhooks/processing}"
}
JSON
)
mka_request PUT "/v1/webhook-endpoint" "$body"

Node

examples/node/webhooks/endpoint/set.mjs

// Point events at your HTTPS address. Keep the secret of the first answer: it is shown once.
import { print, request } from "../../signed-request.mjs";

const answer = await request("PUT", "/v1/webhook-endpoint", {
  body: {
    url: process.env.WEBHOOK_URL ?? "https://shop.example.lk/webhooks/processing",
  },
});
print(answer);

PHP

examples/php/webhooks/endpoint/set.php

<?php
// Point events at your HTTPS address. Keep the secret of the first answer: it is shown once.

declare(strict_types=1);

require __DIR__ . '/../../signed_request.php';

mka_show(mka_request(
    'PUT',
    '/v1/webhook-endpoint',
    [
        'url' => getenv('WEBHOOK_URL') ?: 'https://shop.example.lk/webhooks/processing',
    ],
));

Python

examples/python/webhooks/endpoint/set.py

"""Point events at your HTTPS address. Keep the secret of the first answer: it is shown once."""
import os

from signed_request import request, show

show(request(
    "PUT",
    "/v1/webhook-endpoint",
    body={
        "url": os.environ.get("WEBHOOK_URL", "https://shop.example.lk/webhooks/processing"),
    },
))

Go

examples/go/webhooks/endpoint/set.go

//go:build ignore

// Point events at your HTTPS address. Keep the secret of the first answer: it is shown once.
package main

import (
  "docs.processing.yolotech.cc/examples/signedrequest"
)

func main() {
  signedrequest.Show(signedrequest.Request("PUT", "/v1/webhook-endpoint", map[string]any{
    "url": signedrequest.Env("WEBHOOK_URL", "https://shop.example.lk/webhooks/processing"),
  }, ""))
}

The first answer, 201, carries the signing secret, whsec_…, once. Store it with your other secrets. Changing the address later answers 200 and keeps the secret. Lost it? Roll it.

2. Verify and acknowledge

Node

examples/node/webhooks/receive.mjs

// Receive webhooks: verify each one with the Standard Webhooks library, act on it once.
import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.WEBHOOK_SECRET); // whsec_…, answered once by PUT /v1/webhook-endpoint
const handled = new Set(); // webhook-id of the events acted on; keep this in your database
const versions = new Map(); // the highest version applied, per payment, refund or payout

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    let event;
    try {
      // The exact bytes received, before any JSON parsing; the timestamp must be within 5 minutes.
      event = webhook.verify(Buffer.concat(chunks).toString("utf8"), req.headers);
    } catch {
      res.writeHead(400).end();
      return;
    }
    if (!handled.has(req.headers["webhook-id"])) {
      handled.add(req.headers["webhook-id"]);
      apply(event);
    }
    res.writeHead(204).end(); // answer 2xx within 15 seconds; do slow work after answering
  });
}).listen(Number(process.env.PORT ?? 8080));

function apply(event) {
  const [subject, version] = {
    "payment.status_changed": [event.payment_id, event.payment_version],
    "refund.status_changed": [event.refund_id, event.refund_version],
    "payout.status_changed": [event.payout_id, event.payout_version],
  }[event.type] ?? [event.event_id, 0];
  // Events may come late or twice: an older version than the one applied changes nothing.
  if ((versions.get(subject) ?? 0) > version) return;
  versions.set(subject, version);
  console.log(`verified ${event.type} ${subject} v${version} ${event.status ?? ""}`);
}

PHP

examples/php/webhooks/receive.php

<?php
// Receive one webhook: verify it with the Standard Webhooks library, act on it once.
// Serve it with your web server, or try it with: php -S 0.0.0.0:8080 webhooks/receive.php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use StandardWebhooks\Webhook;
use StandardWebhooks\Exception\WebhookVerificationException;

$webhook = new Webhook(getenv('WEBHOOK_SECRET')); // whsec_…, answered once by PUT /v1/webhook-endpoint
$raw = file_get_contents('php://input'); // the exact bytes received, before any JSON parsing
$headers = array_change_key_case(getallheaders(), CASE_LOWER);
try {
    $event = $webhook->verify($raw, $headers); // the timestamp must be within 5 minutes
} catch (WebhookVerificationException) {
    http_response_code(400);
    exit;
}

// Act once per webhook-id, and never apply an older version over a newer one: keep both in
// your database. Events may come late or twice.
[$subjectField, $versionField] = match ($event['type']) {
    'payment.status_changed' => ['payment_id', 'payment_version'],
    'refund.status_changed' => ['refund_id', 'refund_version'],
    'payout.status_changed' => ['payout_id', 'payout_version'],
    default => ['event_id', null],
};
$version = $versionField === null ? 0 : $event[$versionField];
error_log(sprintf('verified %s %s v%d %s', $event['type'], $event[$subjectField], $version, $event['status'] ?? ''));

http_response_code(204); // answer 2xx within 15 seconds; do slow work after answering

Python

examples/python/webhooks/receive.py

"""Receive webhooks: verify each one with the Standard Webhooks library, act on it once."""
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

from standardwebhooks.webhooks import Webhook, WebhookVerificationError

webhook = Webhook(os.environ["WEBHOOK_SECRET"])  # whsec_…, answered once by PUT /v1/webhook-endpoint
handled = set()  # webhook-id of the events acted on; keep this in your database
versions = {}  # the highest version applied, per payment, refund or payout


def apply(event):
    subject, version = {
        "payment.status_changed": ("payment_id", "payment_version"),
        "refund.status_changed": ("refund_id", "refund_version"),
        "payout.status_changed": ("payout_id", "payout_version"),
    }.get(event["type"], ("event_id", None))
    subject, version = event[subject], event.get(version, 0) if version else 0
    # Events may come late or twice: an older version than the one applied changes nothing.
    if versions.get(subject, 0) > version:
        return
    versions[subject] = version
    print(f"verified {event['type']} {subject} v{version} {event.get('status', '')}", flush=True)


class Receiver(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        try:
            # The exact bytes received; the timestamp must be within 5 minutes.
            event = webhook.verify(raw, {name.lower(): value for name, value in self.headers.items()})
        except WebhookVerificationError:
            self.send_response(400)
            self.end_headers()
            return
        if self.headers["webhook-id"] not in handled:
            handled.add(self.headers["webhook-id"])
            apply(event)
        self.send_response(204)  # answer 2xx within 15 seconds; do slow work after answering
        self.end_headers()

    def log_message(self, *args):
        pass


HTTPServer(("", int(os.environ.get("PORT", "8080"))), Receiver).serve_forever()

Go

examples/go/webhooks/receive.go

//go:build ignore

// Receive webhooks: verify each one with the Standard Webhooks library, act on it once.
package main

import (
  "encoding/json"
  "io"
  "log"
  "net/http"
  "os"
  "sync"

  standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go"
)

type event struct {
  EventID        string `json:"event_id"`
  Type           string `json:"type"`
  Status         string `json:"status"`
  PaymentID      string `json:"payment_id"`
  PaymentVersion int    `json:"payment_version"`
  RefundID       string `json:"refund_id"`
  RefundVersion  int    `json:"refund_version"`
  PayoutID       string `json:"payout_id"`
  PayoutVersion  int    `json:"payout_version"`
}

func main() {
  // whsec_…, answered once by PUT /v1/webhook-endpoint.
  webhook, err := standardwebhooks.NewWebhook(os.Getenv("WEBHOOK_SECRET"))
  if err != nil {
    log.Fatal(err)
  }
  var mu sync.Mutex
  handled := map[string]bool{} // webhook-id of the events acted on; keep this in your database
  versions := map[string]int{} // the highest version applied, per payment, refund or payout

  http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    raw, err := io.ReadAll(r.Body)                          // the exact bytes received, before any JSON parsing
    if err != nil || webhook.Verify(raw, r.Header) != nil { // the timestamp must be within 5 minutes
      w.WriteHeader(http.StatusBadRequest)
      return
    }
    var e event
    if err := json.Unmarshal(raw, &e); err != nil {
      w.WriteHeader(http.StatusBadRequest)
      return
    }
    mu.Lock()
    if id := r.Header.Get("webhook-id"); !handled[id] {
      handled[id] = true
      apply(e, versions)
    }
    mu.Unlock()
    w.WriteHeader(http.StatusNoContent) // answer 2xx within 15 seconds; do slow work after answering
  })
  port := os.Getenv("PORT")
  if port == "" {
    port = "8080"
  }
  log.Fatal(http.ListenAndServe(":"+port, nil))
}

// apply acts on an event; an older version than the one applied changes nothing, as events
// may come late or twice.
func apply(e event, versions map[string]int) {
  subject, version := e.EventID, 0
  switch e.Type {
  case "payment.status_changed":
    subject, version = e.PaymentID, e.PaymentVersion
  case "refund.status_changed":
    subject, version = e.RefundID, e.RefundVersion
  case "payout.status_changed":
    subject, version = e.PayoutID, e.PayoutVersion
  }
  if versions[subject] > version {
    return
  }
  versions[subject] = version
  log.Printf("verified %s %s v%d %s", e.Type, subject, version, e.Status)
}

1. Verify over the raw body, before parsing it: the signature covers the exact bytes. A framework that parses JSON first and serialises it again breaks the signature.
2. Reject a stale timestamp. The libraries refuse one more than 5 minutes off; keep it so.
3. Answer 2xx within 15 seconds, then do the slow work. Anything else — a timeout, a redirect, a 5xx — is retried.
4. Act once per webhook-id: a retry carries the same id (ordering).

Each event carries three headers:

Header
webhook-id	The event’s id; the same on every retry.
webhook-timestamp	Unix seconds of this attempt.
webhook-signature	v1, and the base64 HMAC-SHA256 of id.timestamp.body with your secret. While a rolled secret overlaps, one signature per secret, space-separated.

The events

Type	When	Key fields
payment.status_changed	A payment became requires_action, processing, succeeded, failed or cancelled.	payment_id, payment_version, status, data.merchant_order_id, data.amount, data.amount_received
refund.status_changed	A refund was asked, taken, sent or failed.	refund_id, refund_version, payment_id, status
payout.status_changed	A payout was created, taken, sent, failed or cancelled.	payout_id, payout_version, status, data.merchant_payout_id, data.fee
webhook.test	You asked for a test.	—

Every field is in the events reference. Ignore event types and fields you do not know: new ones are added within v1.

3. Test it

curl

examples/curl/webhooks/endpoint/send-test-event.sh

#!/usr/bin/env bash
# Send a webhook.test event now and see how your endpoint answered.
set -euo pipefail
. "$(dirname "$0")/../../signed-request.sh"

mka_request POST "/v1/webhook-endpoint/test"

Node

examples/node/webhooks/endpoint/send-test-event.mjs

// Send a webhook.test event now and see how your endpoint answered.
import { print, request } from "../../signed-request.mjs";

const answer = await request("POST", "/v1/webhook-endpoint/test");
print(answer);

PHP

examples/php/webhooks/endpoint/send-test-event.php

<?php
// Send a webhook.test event now and see how your endpoint answered.

declare(strict_types=1);

require __DIR__ . '/../../signed_request.php';

mka_show(mka_request('POST', '/v1/webhook-endpoint/test'));

Python

examples/python/webhooks/endpoint/send_test_event.py

"""Send a webhook.test event now and see how your endpoint answered."""
from signed_request import request, show

show(request("POST", "/v1/webhook-endpoint/test"))

Go

examples/go/webhooks/endpoint/send-test-event.go

//go:build ignore

// Send a webhook.test event now and see how your endpoint answered.
package main

import (
  "docs.processing.yolotech.cc/examples/signedrequest"
)

func main() {
  signedrequest.Show(signedrequest.Request("POST", "/v1/webhook-endpoint/test", nil, ""))
}

The answer says whether your endpoint took it and with what status. Every event and every attempt is also listed under Developers → Webhooks in the console, and by the API:

curl

examples/curl/webhooks/deliveries/list.sh

#!/usr/bin/env bash
# Your deliveries, newest first, 50 a page.
set -euo pipefail
. "$(dirname "$0")/../../signed-request.sh"

mka_request GET "/v1/webhook-deliveries"

Node

examples/node/webhooks/deliveries/list.mjs

// Your deliveries, newest first, 50 a page.
import { print, request } from "../../signed-request.mjs";

const answer = await request("GET", "/v1/webhook-deliveries");
print(answer);

PHP

examples/php/webhooks/deliveries/list.php

<?php
// Your deliveries, newest first, 50 a page.

declare(strict_types=1);

require __DIR__ . '/../../signed_request.php';

mka_show(mka_request('GET', '/v1/webhook-deliveries'));

Python

examples/python/webhooks/deliveries/list.py

"""Your deliveries, newest first, 50 a page."""
from signed_request import request, show

show(request("GET", "/v1/webhook-deliveries"))

Go

examples/go/webhooks/deliveries/list.go

//go:build ignore

// Your deliveries, newest first, 50 a page.
package main

import (
  "docs.processing.yolotech.cc/examples/signedrequest"
)

func main() {
  signedrequest.Show(signedrequest.Request("GET", "/v1/webhook-deliveries", nil, ""))
}