Webhooks

General Information

How It Works

1. Register your webhook URL in the whitelist (contact support)
2. Create an invoice with the paymentStatusChangeWebhookUrl field set to your registered URL
3. Store the secret returned in paymentStatusChangeWebhookSecret - you'll need it to verify webhook signatures
4. Receive webhooks when payment status changes (e.g., from processing to done)

Invoice Fields for Webhooks

Creating an Invoice with Webhook

graphql
mutation createInvoice {
  obj: createInvoice(
    data: {
      dv: 1,
      sender: {dv: 1, fingerprint: "my-service"},
      organization: {connect: {id: "e40b5367-49a8-4340-9eed-802538331326"}},
      property: {connect: {id: "809bff2d-b1ff-485e-b2e9-33b4c5974d3b"}},
      unitName: "42",
      unitType: flat,
      clientPhone: "+79999999999",
      clientName: "John Doe",
      toPay: "1500",
      rows: [{name: "Service payment", count: 1, toPay: "1500", isMin: false}],
      paymentType: online,
      status: published,
      paymentStatusChangeWebhookUrl: "https://your-service.com/webhook/payment"
    }
  ) {
    id
    number
    status
    paymentStatusChangeWebhookUrl
    paymentStatusChangeWebhookSecret
  }
}

Webhook Payload

json
{
  "__typename": "Payment",
  "id": "payment-uuid",
  "v": 2,
  "dv": 1,
  "status": "done",
  "amount": "1500.00000000",
  "currencyCode": "RUB",
  "organization": {
    "__typename": "Organization",
    "id": "org-uuid",
    "name": "Organization Name"
  },
  "invoice": {
    "__typename": "Invoice",
    "id": "invoice-uuid",
    "number": 15,
    "toPay": "1500.00000000"
  },
  "receipt": null,
  "createdAt": "2024-12-16T10:00:00.000Z",
  "updatedAt": "2024-12-16T10:05:00.000Z"
}

Payment Statuses

Webhook Headers

Verifying Webhook Signatures

Node.js Example

javascript
const crypto = require('node:crypto')

function verifyWebhookSignature(rawBody, signature, secret, algorithm) {
    const allowedAlgorithms = new Set(['sha256', 'sha384', 'sha512'])
    if (!allowedAlgorithms.has(algorithm)) return false

    const expectedSignature = crypto
        .createHmac(algorithm, secret)
        .update(rawBody)
        .digest('hex')
    
    return signature === expectedSignature
}

// Express.js middleware example
app.post('/webhook/payment', express.text({ type: 'application/json' }), (req, res) => {
    const signature = req.headers['x-webhook-signature']
    const algorithm = req.headers['x-webhook-signature-algorithm'] || 'sha256'
    const webhookId = req.headers['x-webhook-id']
    const rawBody = req.body
    
    // Get the stored secret for this invoice
    const secret = getStoredSecretForInvoice(invoiceId)
    
    if (!verifyWebhookSignature(rawBody, signature, secret, algorithm)) {
        return res.status(401).json({ error: 'Invalid signature' })
    }
    
    const payload = JSON.parse(rawBody)
    
    // Process the webhook
    console.log(`Payment ${payload.id} status changed to ${payload.status}`)
    
    res.status(200).json({ status: 'ok' })
})

URL Whitelist

Best Practices

1. Always verify signatures - Never trust webhook payloads without signature verification
2. Respond quickly - Return a 2xx response within a few seconds to acknowledge receipt
3. Handle duplicates - Use X-Webhook-Id to detect and handle duplicate deliveries
4. Store secrets securely - Keep webhook secrets encrypted and never expose them in logs
5. Use HTTPS - Always use HTTPS endpoints in production

Retry Policy

Error Handling

• Return 200 OK for successful processing
• Return 401 Unauthorized for signature verification failures
• Return 500 Internal Server Error for temporary failures (will trigger retry)