İçeriğe atlayın

API

Bu sayfada

İmzalar

X-Webhook-Signature başlığını HMAC-SHA256 ile doğrulayın, imzaları güvenle karşılaştırın, zaman damgası kurallarını uygulayın ve sır rotasyonunu destekleyin.

Her teslimat, Webhook Secret'ınızla HMAC-SHA256 kullanılarak imzalanır. İşlemeden önce imzayı doğrulayın.

Başlık Açıklama
X-Webhook-Signature Bileşik imza: t={timestamp},v1={hmac_hex}
X-Webhook-Timestamp Bu denemenin Unix saniyesi — imzanın t olarak taşıdığı değerin aynısı
X-Webhook-Id Bu teslimatın evt_… kimliği; günlükleriniz ve yineleme ayıklamanız için

Doğrulamaya yalnızca ilk başlık girer. Zaman damgasını ve bir veya daha fazla HMAC değerini o taşır:

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

HMAC, timestamp + "." + raw_body üzerinde hesaplanır:

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

Zaman damgası, tekrar saldırılarını önlemek için imzalı yükün parçasıdır. |now - timestamp| > 300 saniye olan teslimatları reddedin.

Doğrulama adımları

  1. X-Webhook-Signature değerini ayrıştırın: t (zaman damgası) ve her v1 değerini çıkarın
  2. |now - t| > 300 saniye ise reddedin
  3. signature_payload = str(t) + "." + raw_body oluşturun
  4. HMAC-SHA256(webhook_secret, signature_payload) hesaplayın
  5. Sonucu küçük harf hex'e çevirin
  6. Zamanlama güvenli bir karşılaştırmayla her v1 değeriyle karşılaştırın — herhangi bir eşleşme = geçerli
  7. Hiçbir imza eşleşmezse HTTP 401 ile reddedin

İmzaları her zaman zamanlama güvenli bir fonksiyonla karşılaştırın — crypto.timingSafeEqual (Node), hmac.compare_digest (Python), hash_equals (PHP), MessageDigest.isEqual (Java), CryptographicOperations.FixedTimeEquals (.NET). Düz ==, zamanlama analiziyle sırrı bayt bayt sızdırır.

Sır rotasyonu

Webhook Secret rotasyonu sırasında Paymos 24 saat boyunca çift imza gönderir; böylece kesintisiz geçiş yaparsınız. Başlık iki v1 değeri taşır: t={timestamp},v1={current_hmac},v1={previous_hmac}. Güncel veya önceki sırla eşleşen bir imza kabul edilir; mevcut kontrolünüz (adım 6) rotasyon boyunca geçmeye devam eder.

Doğrulama kodu

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);
Webhook yükleri Teslimat ve yeniden denemeler