Setting Up Webhooks

Receive real-time notifications when invoice statuses change.

1. Create a webhook endpoint

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/yona",
    "events": ["invoice.approved", "invoice.rejected", "invoice.submission_failed"],
    "description": "Invoice status notifications"
  }'

2. Build a receiver

Your endpoint must verify the signature, process the event, and return 200 within 10 seconds.


import express from 'express';
import { verifyWebhook } from '@useyona/einvoice-js/webhooks';
 
const app = express();
 
app.post('/webhooks/yona', express.json(), (req, res) => {
  try {
    const event = verifyWebhook(
      req.body,
      req.headers,
      process.env.WEBHOOK_SECRET!,
    );
 
    switch (event.type) {
      case 'invoice.approved':
        handleApproved(event.data);
        break;
      case 'invoice.rejected':
        handleRejected(event.data);
        break;
      case 'invoice.submission_failed':
        handleFailed(event.data);
        break;
    }
 
    res.status(200).json({ received: true });
  } catch (err) {
    res.status(400).json({ error: 'Invalid signature' });
  }
});

💡 Raw body or parsed JSON — both work

You can pass either the raw body (Buffer/string) or JSON.stringify(req.body) — the SDK handles both. Using express.json() or express.raw() are both fine.

3. Test your endpoint

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks/wh_6f7a8b9c-0d1e-2345-6789-0abcdef12345/test \
  -H "Authorization: Bearer sk_test_your_key_here"

Available events

Invoice events

Event	When it fires
`invoice.created`	Invoice created (draft status)
`invoice.updated`	Draft invoice modified
`invoice.submitted`	Invoice queued for submission to tax authority
`invoice.approved`	Tax authority accepted the invoice
`invoice.rejected`	Tax authority rejected the invoice
`invoice.submission_failed`	Submission failed before tax authority response
`invoice.cancelled`	Invoice cancelled (credit note created)
`invoice.status.changed`	Invoice status changed via authority callback
`invoice.retry_scheduled`	Failed invoice re-queued for retry

Payment events

Event	When it fires
`payment.created`	Payment initiated
`payment.succeeded`	Payment completed
`payment.failed`	Payment declined or failed
`billing_account.low_balance`	Credit balance dropped below threshold

Seller & Buyer events

Event	When it fires
`seller.created`	New seller registered
`seller.updated`	Seller details changed
`seller.tax_number_verified`	Seller TIN verification succeeded
`buyer.created`	New buyer registered
`buyer.updated`	Buyer details changed
`buyer.tax_number_verified`	Buyer TIN verification succeeded

💡 Full event list

See Core Concepts — Webhooks for the complete list of all event types including organization, user, subscription, and API key events.

Retry behavior

Failed deliveries are retried up to 3 total attempts (1 initial + 2 retries) with exponential backoff. You can manually retry:

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/webhooks/deliveries/del_8b9c0d1e-2f3a-4567-8901-bcdef1234567/retry \
  -H "Authorization: Bearer sk_test_your_key_here"