Перейти к содержимому

API

На странице

Подпись

Проверяйте заголовок X-Webhook-Signature по HMAC-SHA256, безопасно сравнивайте подпись, контролируйте время и меняйте секрет без простоя.

Каждая доставка подписана HMAC-SHA256 с вашим Webhook Secret. Проверьте подпись до обработки.

Заголовок Описание
X-Webhook-Signature Составная подпись: t={timestamp},v1={hmac_hex}

Заголовок содержит timestamp и одно или несколько значений HMAC:

X-Webhook-Signature: t=1739281200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC вычисляется над timestamp + "." + raw_body:

signature_payload = str(timestamp) + "." + raw_body
hmac_hex = HMAC-SHA256(webhook_secret, signature_payload)  # lowercase hex

Timestamp входит в подписываемый payload, чтобы защититься от replay-атак. Отклоняйте доставки, у которых |now - timestamp| > 300 секунд.

Шаги проверки

  1. Разберите X-Webhook-Signature: извлеките t (timestamp) и все значения v1
  2. Отклоните, если |now - t| > 300 секунд
  3. Сформируйте signature_payload = str(t) + "." + raw_body
  4. Вычислите HMAC-SHA256(webhook_secret, signature_payload)
  5. Преобразуйте результат в hex-строку нижнего регистра
  6. Сравните с каждым значением v1 через timing-safe сравнение — любое совпадение = валидно
  7. Если ни одна подпись не совпала — ответьте HTTP 401

Всегда сравнивайте подписи timing-safe функцией — crypto.timingSafeEqual (Node), hmac.compare_digest (Python), hash_equals (PHP), MessageDigest.isEqual (Java), CryptographicOperations.FixedTimeEquals (.NET). Обычный == сливает секрет побайтно через timing-анализ.

Ротация секрета

При ротации Webhook Secret Paymos в течение 24 часов отправляет двойную подпись, чтобы вы могли перейти на новый секрет без простоя. Заголовок содержит два значения v1: t={timestamp},v1={current_hmac},v1={previous_hmac}. Подпись принимается, если совпадает либо с текущим, либо с предыдущим секретом, — поэтому ваша проверка (шаг 6) продолжает работать всю ротацию.

Код проверки

import { WebhookVerifier } from '@paymos/sdk';

const verifier = new WebhookVerifier(process.env.PAYMOS_WEBHOOK_SECRET);

// Keep the body as a Buffer until verification succeeds.
const event = verifier.constructEvent(signatureHeader, rawBody);
console.log(event.eventId, event.eventType, event.data);

import os

from paymos import WebhookVerifier

verifier = WebhookVerifier(os.environ["PAYMOS_WEBHOOK_SECRET"])

# Keep raw_body as bytes until verification succeeds.
event = verifier.construct_event(signature_header, raw_body)
print(event["event_id"], event["event_type"], event["data"])

<?php
use Paymos\Webhook\WebhookEvent;
use Paymos\Webhook\WebhookVerifier;

$verifier = new WebhookVerifier(getenv('PAYMOS_WEBHOOK_SECRET'));

// Keep $rawBody unchanged until verification succeeds.
$payload = $verifier->decodeVerifiedPayload($signatureHeader, $rawBody);
$event = new WebhookEvent($payload);
echo $event->id() . ' ' . $event->type();

package main

import (
	"fmt"
	"os"
	"time"

	paymos "github.com/Paymos-labs/go-sdk/v2"
)

type invoiceEventData struct {
	InvoiceID string `json:"invoice_id"`
}

func handleWebhook(signatureHeader string, rawBody []byte) error {
	verifier, err := paymos.NewWebhookVerifier(os.Getenv("PAYMOS_WEBHOOK_SECRET"), 5*time.Minute)
	if err != nil {
		return err
	}
	var event paymos.WebhookEvent[invoiceEventData]
	if err := verifier.ConstructEvent(signatureHeader, rawBody, time.Now(), &event); err != nil {
		return err
	}
	fmt.Println(event.EventID, event.EventType, event.Data.InvoiceID)
	return nil
}

using Paymos;

var verifier = new WebhookVerifier(
    Environment.GetEnvironmentVariable("PAYMOS_WEBHOOK_SECRET")!);

// Keep rawBody as ReadOnlySpan<byte> until verification succeeds.
var webhook = verifier.ConstructEvent<InvoiceEventData>(signatureHeader, rawBody);
Console.WriteLine($"{webhook.EventId} {webhook.EventType} {webhook.Data.InvoiceId}");

public sealed record InvoiceEventData(string InvoiceId);

import com.fasterxml.jackson.databind.JsonNode;
import io.paymos.WebhookEvent;
import io.paymos.WebhookVerifier;
import java.time.Instant;

WebhookVerifier verifier = new WebhookVerifier(System.getenv("PAYMOS_WEBHOOK_SECRET"));

// Keep rawBody as byte[] until verification succeeds.
WebhookEvent<JsonNode> event =
    verifier.constructEvent(signatureHeader, rawBody, Instant.now());
System.out.println(event.eventId() + " " + event.eventType() + " " + event.data());

require 'paymos'

verifier = Paymos::WebhookVerifier.new(ENV.fetch('PAYMOS_WEBHOOK_SECRET'))

# Keep raw_body as the original String until verification succeeds.
event = verifier.construct_event(signature_header, raw_body)
puts "#{event.event_id} #{event.event_type} #{event.data}"

use paymos::{Invoice, WebhookEvent, WebhookVerifier};

let verifier = WebhookVerifier::new(std::env::var("PAYMOS_WEBHOOK_SECRET")?)?;

// Keep raw_body as &[u8] until verification succeeds.
let event: WebhookEvent<Invoice> = verifier.construct_event(signature_header, raw_body)?;
println!("{} {} {}", event.event_id, event.event_type, event.data.invoice_id);
Payload вебхуков Доставка и retry