Webhooks Creation API

Receive real-time updates about payment status changes by configuring webhooks with the Elyxa API. All API requests should be made to the base URL with proper authentication.

Base URL

https://elyxa.app/api

Authentication

All API requests require authentication using your API key. Include it in the request header:

Authorization: Bearer YOUR_API_KEY

Webhook Configuration

Webhooks are configured through your merchant dashboard at https://elyxa.app/dashboard/webhooks. You can set up multiple webhook endpoints to receive real-time payment notifications.

Setting Up Webhooks

Navigate to your merchant dashboard
Go to the Webhooks section
Click "Add Webhook"
Enter your webhook endpoint URL
Select the events you want to receive
Save your configuration

Webhook Configuration Fields

Field	Description
URL	Your webhook endpoint URL (must be HTTPS)
Events	Select which events to receive notifications for
Description	Optional description for your reference
Status	Active/Inactive toggle for the webhook

Webhook Events

The following events are available for webhook notifications:

invoice.paid - Invoice has been paid
invoice.expired - Invoice has expired
invoice.cancelled - Invoice was cancelled

Webhook Payload Examples

Invoice Paid Event

{
  "event": "invoice.paid",
  "invoiceId": "WfW5Dd1ASHSj4ZHhMC5yTA",
  "amount": 25.50,
  "currency": "USD",
  "status": "paid",
  "paidAmount": 25.50,
  "paidAt": "2024-01-15T10:25:00Z",
  "paymentMethods": [
    {
      "methodId": "BITCOIN",
      "isPaid": true,
      "paidAmount": 25.50,
      "paidAt": "2024-01-15T10:25:00Z"
    }
  ],
  "metadata": {},
  "timestamp": 1705314300000
}

Invoice Expired Event

{
  "event": "invoice.expired",
  "invoiceId": "WfW5Dd1ASHSj4ZHhMC5yTA",
  "amount": 25.50,
  "currency": "USD",
  "status": "expired",
  "paymentMethods": [
    {
      "methodId": "BITCOIN",
      "isPaid": false
    }
  ],
  "metadata": {},
  "timestamp": 1705314300000
}

Invoice Cancelled Event

{
  "event": "invoice.cancelled",
  "invoiceId": "WfW5Dd1ASHSj4ZHhMC5yTA",
  "amount": 25.50,
  "currency": "USD",
  "status": "cancelled",
  "paymentMethods": [
    {
      "methodId": "BITCOIN",
      "isPaid": false
    }
  ],
  "metadata": {},
  "timestamp": 1705314300000
}

Request Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The webhook endpoint URL where notifications will be sent
`events`	array	Yes	Array of events to subscribe to
`description`	string	No	Optional description for the webhook

Response Fields

Field	Type	Description
`webhookId`	string	Unique identifier for the created webhook
`url`	string	The configured webhook endpoint URL
`events`	array	Events the webhook is subscribed to
`status`	string	Current status of the webhook (active/inactive)
`createdAt`	string	ISO timestamp when the webhook was created
`success`	boolean	Indicates if the webhook was created successfully

Webhook Security

Signature Verification

All webhook requests include a signature header for verification. You'll receive a webhook secret when you create your webhook in the dashboard.

Headers you'll receive:

X-Webhook-Event: invoice.paid
X-Webhook-Signature: sha256=abc123...
Content-Type: application/json
User-Agent: Crypto-Town-Webhook/1.0

Verification Process

To verify webhook authenticity, you should:

Extract the signature from the X-Webhook-Signature header
Use your webhook secret to generate an HMAC-SHA256 hash of the request body
Compare the generated hash with the received signature

Example verification (Node.js):

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature.replace('sha256=', ''), 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Error Responses

If the webhook creation fails, you'll receive an error response:

{
  "error": "Invalid webhook URL",
  "success": false
}

Example Webhook Endpoint Implementation

Here's an example of how to implement a webhook endpoint to receive notifications:

Express.js Example

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhook-endpoint', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const event = req.headers['x-webhook-event'];
  const payload = JSON.stringify(req.body);
  
  // Verify webhook signature using your secret
  const expectedSignature = crypto
    .createHmac('sha256', 'YOUR_WEBHOOK_SECRET')
    .update(payload)
    .digest('hex');
    
  if (signature !== `sha256=${expectedSignature}`) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process the webhook event
  console.log(`Received ${event} event:`, req.body);
  
  // Handle different event types
  switch (event) {
    case 'invoice.paid':
      // Process payment confirmation
      break;
    case 'invoice.expired':
      // Handle expired invoice
      break;
    case 'invoice.cancelled':
      // Handle cancelled invoice
      break;
  }
  
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});

Python Flask Example

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhook-endpoint', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    event = request.headers.get('X-Webhook-Event')
    payload = request.get_data()
    
    # Verify webhook signature
    expected_signature = hmac.new(
        b'YOUR_WEBHOOK_SECRET',
        payload,
        hashlib.sha256
    ).hexdigest()
    
    if signature != f'sha256={expected_signature}':
        return jsonify({'error': 'Invalid signature'}), 401
    
    # Process webhook event
    data = request.get_json()
    print(f"Received {event} event: {data}")
    
    # Handle the event based on type
    if event == 'invoice.paid':
        # Process payment confirmation
        pass
    
    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(debug=True, port=3000)

Managing Webhooks

All webhook management (create, edit, delete, enable/disable) is done through your merchant dashboard at https://elyxa.app/dashboard/webhooks.

Dashboard Features

Create new webhooks with custom endpoints and event selection
Edit existing webhooks to change URLs or event subscriptions
Enable/disable webhooks without deleting them
View webhook delivery history and success/failure rates
Regenerate webhook secrets for security

Best Practices

HTTPS Only: Always use HTTPS endpoints for webhooks
Idempotency: Handle duplicate webhook events gracefully
Timeout: Respond to webhooks within 5 seconds
Retry Logic: Implement retry logic for failed webhook deliveries
Logging: Log all webhook events for debugging purposes

Webhooks Creation API

On this page