Webhooks

Webhooks notify your application about payment events in real-time.

Events

Event	Description
payment.created	Payment created
payment.processing	Payment submitted for processing
payment.completed	Payment successful
payment.failed	Payment failed
payment.returned	Payment returned by bank

Create Webhook

POST /api/v1/webhooks

curl -X POST https://api.paystream.fi/api/v1/webhooks \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": ["payment.completed", "payment.failed"]
  }'

Webhook Payload

{
  "id": "evt_abc123",
  "type": "payment.completed",
  "data": {
    "paymentId": "pay_xyz789",
    "amount": 10000,
    "status": "completed"
  },
  "timestamp": "2026-02-19T00:00:00Z"
}

Signature Verification

Webhooks are signed with your webhook secret. Verify the signature:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}