Zafira

Alternar tema

Webhook Management API ​

Get Webhook Details ​

Retrieves all webhooks associated with the wallet.

Endpoint ​

http
GET /api/wallet/{wallet}/webhook

Parameters ​

  • wallet (integer): Wallet ID

Response ​

json
{
  "status": "success",
  "message": "Webhooks fetched successfully",
  "data": [
    {
      "id": 1,
      "url": "https://example.com/webhook",
      "type": "charge",
      "status": "active",
      "events": ["created", "confirmed"],
      "headers": {
        "Authorization": "Bearer eyb21...",
        "Custom-Header": "custom-value"
      },
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-01 00:00:00"
    }
  ]
}

Example Request ​

bash
curl -H "Authorization: Bearer {token}" \
     https://zafira-app.vratts.com/api/wallet/1/webhook

Get Webhook Types ​

Retrieves available webhook types.

Endpoint ​

http
GET /api/wallet/{wallet}/webhook/types

Parameters ​

  • wallet (integer): Wallet ID

Response ​

json
{
  "status": "success",
  "message": "Webhooks types fetched successfully",
  "data": ["charge", "transaction", "balance", "token", "wallet"]
}

Example Request ​

bash
curl -H "Authorization: Bearer {token}" \
     https://zafira-app.vratts.com/api/wallet/1/webhook/types

Get Webhook Event Details ​

Retrieves details for a specific webhook event.

Endpoint ​

http
GET /api/wallet/{wallet}/webhook/event/{event}

Parameters ​

  • wallet (integer): Wallet ID
  • event (string): Event name

Response ​

json
{
  "status": "success",
  "message": "Webhooks event fetched successfully",
  "data": {
    "event_name": "charge.created",
    "description": "Triggered when a charge is created",
    "payload": {
      "charge_id": 1,
      "wallet_id": 1,
      "amount": "0.1",
      "token": "ETH",
      "uuid": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Example Request ​

bash
curl -H "Authorization: Bearer {token}" \
     https://zafira-app.vratts.com/api/wallet/1/webhook/event/charge.created

Create Webhook ​

Creates a new webhook for the wallet.

Endpoint ​

http
POST /api/wallet/{wallet}/webhook/create

Parameters ​

  • wallet (integer): Wallet ID

Request Body ​

json
{
  "url": "https://example.com/webhook",
  "type": "charge",
  "events": ["created", "confirmed"],
  "signature": "your-webhook-secret",
  "with_headers": {
    "Authorization": "Bearer eyb21...",
    "Custom-Header": "custom-value"
  }
}

Request Parameters ​

  • url (string, required): Webhook URL
  • type (string, required): Webhook type - "charge", "transaction", "balance", "token", "wallet"
  • events (array, required): Array of events to listen for
  • signature (string, optional): Webhook signature for verification
  • with_headers (object, optional): Additional headers to include

Response ​

json
{
  "status": "success",
  "message": "Webhooks created successfully",
  "data": {
    "id": 1,
    "url": "https://example.com/webhook",
    "type": "charge",
    "status": "active",
    "events": ["created", "confirmed"],
    "headers": {},
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-01 00:00:00"
  }
}

Example Request ​

bash
curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://example.com/webhook","type":"charge","events":["created","confirmed"],"signature":"webhook-secret"}' \
     https://zafira-app.vratts.com/api/wallet/1/webhook/create

Delete Webhook ​

Deletes a specific webhook.

Endpoint ​

http
GET /api/wallet/{wallet}/webhook/delete/{webhook}

Parameters ​

  • wallet (integer): Wallet ID
  • webhook (integer): Webhook ID

Response ​

json
{
  "status": "success",
  "message": "Webhook deleted successfully",
  "data": {
    "id": 1,
    "url": "https://example.com/webhook",
    "type": "charge",
    "events": ["created", "confirmed"],
    "signature": "webhook_secret",
    "status": "active",
    "deleted_at": "2024-01-01 00:00:00"
  }
}

Example Request ​

bash
curl -H "Authorization: Bearer {token}" \
     https://zafira-app.vratts.com/api/wallet/1/webhook/delete/1

Webhook Types and Events ​

Charge Events ​

  • charge.created: Triggered when a charge is created
  • charge.paid: Triggered when a charge is paid
  • charge.expired: Triggered when a charge expires
  • charge.failed: Triggered when a charge payment fails

Transaction Events ​

  • transaction.created: Triggered when a transaction is created
  • transaction.confirmed: Triggered when a transaction is confirmed
  • transaction.failed: Triggered when a transaction fails

Balance Events ​

  • balance.updated: Triggered when wallet balance changes

Token Events ​

  • token.added: Triggered when a token is added to wallet
  • token.removed: Triggered when a token is removed from wallet

Wallet Events ​

  • wallet.created: Triggered when a wallet is created
  • wallet.updated: Triggered when a wallet is updated

Webhook Model Details ​

Fields ​

  • id (integer): Unique webhook identifier
  • url (string): Webhook endpoint URL
  • type (string): Webhook type
  • status (string): Webhook status ("active" or "inactive")
  • events (array): Array of events to monitor
  • headers (object): Additional headers for webhook requests
  • created_at (datetime): Creation timestamp
  • updated_at (datetime): Last update timestamp

Hidden Fields (for security) ​

  • signature: Encrypted webhook signature
  • wallet_id: Associated wallet ID

Webhook Status Values ​

  • active: Webhook is enabled and will receive events
  • inactive: Webhook is disabled and will not receive events

Webhook Security ​

Signature Verification ​

When a signature is provided, webhooks include a signature header for verification:

json
{
  "headers": {
    "X-Webhook-Signature": "sha256=hash_of_payload"
  }
}

Signature Generation ​

The signature is generated using HMAC-SHA256:

php
$signature = hash_hmac('sha256', $payload, $secret);

Verification Example ​

javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${expectedSignature}` === signature;
}

Webhook Payload Examples ​

Charge Created Event ​

json
{
  "event": "charge.created",
  "data": {
    "charge_id": 1,
    "wallet_id": 1,
    "amount": "0.100000000000000000",
    "token": "ETH",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "expires": 300,
    "created_at": "2024-01-01 00:00:00"
  }
}

Transaction Confirmed Event ​

json
{
  "event": "transaction.confirmed",
  "data": {
    "transaction_id": 1,
    "wallet_id": 1,
    "amount": "0.100000000000000000",
    "token": "ETH",
    "tx_hash": "0x1234567890abcdef...",
    "block_number": 12345678,
    "status": "confirmed",
    "confirmed_at": "2024-01-01 00:00:00"
  }
}

Balance Updated Event ​

json
{
  "event": "balance.updated",
  "data": {
    "wallet_id": 1,
    "token": "ETH",
    "old_balance": "1.000000000000000000",
    "new_balance": "1.100000000000000000",
    "change": "0.100000000000000000",
    "updated_at": "2024-01-01 00:00:00"
  }
}

Error Handling ​

Common Errors ​

Webhook Not Found (404) ​

json
{
  "status": "error",
  "message": "Webhook not found",
  "data": null
}

Invalid URL (422) ​

json
{
  "status": "error",
  "message": "The url field must be a valid URL",
  "data": {
    "url": ["The url field must be a valid URL."]
  }
}

Invalid Type (422) ​

json
{
  "status": "error",
  "message": "The selected type is invalid",
  "data": {
    "type": ["The selected type is invalid."]
  }
}

Invalid Events (422) ​

json
{
  "status": "error",
  "message": "The events field is required",
  "data": {
    "events": ["The events field is required."]
  }
}

Webhook Delivery ​

Retry Logic ​

  • Failed webhook deliveries are retried up to 3 times
  • Retry intervals: 1 minute, 5 minutes, 15 minutes
  • Webhooks that fail after all retries are marked as failed

Timeout Settings ​

  • Webhook timeout: 30 seconds
  • Connection timeout: 10 seconds
  • Read timeout: 20 seconds

Delivery Status ​

Webhooks track delivery status:

  • pending: Waiting to be delivered
  • delivered: Successfully delivered
  • failed: Delivery failed after all retries
  • retrying: Currently retrying delivery

Best Practices ​

Webhook Implementation ​

  • Always verify webhook signatures
  • Implement idempotency to handle duplicate events
  • Use HTTPS endpoints for webhook URLs
  • Respond quickly to webhook requests (within 5 seconds)

Error Handling ​

  • Return appropriate HTTP status codes
  • Log webhook delivery failures
  • Implement proper error responses
  • Monitor webhook delivery success rates

Security ​

  • Use strong, unique signatures
  • Validate all incoming webhook data
  • Implement rate limiting on webhook endpoints
  • Monitor for suspicious webhook activity

Next Steps ​

Released under the MIT License.

Copyright © 2024 Zafira Team