Skip to main content

🧵 Send Transaction and Receive Notification via Webhook

This guide documents the full workflow for sending a blockchain transaction and receiving asynchronous status updates via webhook events. It covers how to subscribe to the necessary events and how to interpret transaction outcomes (mined or failed).

🌟 Objective: Ensure clients can programmatically send transactions and handle outcomes via webhook notifications.

📚 OpenAPI Documentation​

✨ Workflow Summary​

This workflow includes the following steps:

  1. 🔹 Subscribe to webhook events for TX_MINED and TX_FAILED.
  2. 🔹 Send a blockchain transaction (e.g. minting an ERC3643 token).
  3. 🔹 Receive asynchronous notification via webhook on transaction success or failure.

📋 Workflow Steps Table​

StepAPI OperationMethodParametersOutputsDescription
Subscribe to All TX EventsPOST /subscriptions/webhooks-eventTypes, callbackUrlsubscriptionIdSubscribes to TX_MINED and TX_FAILED for all transactions by the client
OR: Subscribe by TokenPOST /tokens/{tokenId}/subscriptions/webhook-tokenId, eventTypes, callbackUrlsubscriptionIdSubscribes to TX_MINED and TX_FAILED for a specific token only
Mint Token (example tx)POST /erc3643/{tokenId}/mint-recipient, amount, tokenIdtransactionIdSends a token mint transaction
Receive Webhook EventCallback to callbackUrl-eventType, txHash, status-Event TX_MINED or TX_FAILED sent to the registered callback URL

🎨 Workflow Visualizations​

🌊 Mermaid Sequence Diagram​

📝 Step-by-Step Implementation​

Step 1: Subscribe to Webhook Events​

Choose between global subscription (all transactions) or token-specific subscription.

Subscribe to all transaction events across all tokens for your client.

Endpoint: POST /subscriptions/webhooks

Request Body:

{
  "event": "TX_MINED",
  "callbackUrl": "https://your-server.com/webhooks/blockchain"
}

Request Parameters:

  • eventTypes: Event type to subscribe to
  • callbackUrl: Your server endpoint that will receive webhook notifications

Response:

{
  "id": "sub_123e4567-e89b-12d3-a456-426614174000",
  "event": "TX_FAILED",
  "callbackUrl": "https://your-server.com/webhooks/blockchain"
}

Option B: Token-Specific Subscription​

Subscribe to events for a specific token only.

Endpoint: POST /tokens/{tokenId}/subscriptions/webhook

Path Parameters:

  • tokenId: UUID of the specific token

Request Body:

{
  "event": "TX_FAILED",
  "callbackUrl": "https://your-server.com/webhooks/token-events"
}

Response:

{
  "id": "sub_456e7890-e89b-12d3-a456-426614174111",
  "event": "TX_FAILED",
  "callbackUrl": "https://your-server.com/webhooks/token-events"
}

Step 2: Send a Blockchain Transaction​

Execute any blockchain transaction (using mint as an example).

Endpoint: POST /erc3643/{tokenId}/mint

Request Body:

{
  "to": ["0x1234567890abcdef1234567890abcdef12345678"],
  "amount": ["1000000000000000000"]
}

Request Parameters:

  • to: Array of recipient addresses (must have valid identity)
  • amount: Amounts in wei (1 token = 10^18 wei for 18 decimals)

Response:

{
  "id": "tx_789e0123-e89b-12d3-a456-426614174222"
}

Save the transaction id to correlate with webhook events.

Step 3: Receive Webhook Notifications​

Your server will receive POST requests to the callbackUrl specified in Step 1.

TX_MINED Event (Success)​

Received when the transaction is successfully mined on the blockchain.

{
  "type": "TX_MINED",
  "event": {
    "txUUID": "tx_789e0123-e89b-12d3-a456-426614174222",
    "txHash": "0xb5c8bd9430b6cc87a0e2fe110ece6bf527fa4f170a4bc8cd032f768fc5219838",
    "timestamp": 1634567890
  }
}

Event Fields:

  • txUUID: Your transaction ID from Step 2
  • txHash: Blockchain transaction hash for verification
  • timestamp: Unix timestamp of mining

TX_FAILED Event (Failure)​

Received when the transaction fails.

{
  "type": "TX_FAILED",
  "event": {
    "txUUID": "tx_789e0123-e89b-12d3-a456-426614174222",
    "reason": "Insufficient balance",
    "timestamp": 1634567890
  }
}

Step 4: Handle Webhook in Your Server​

Implement a webhook handler to process notifications.

💡 Key Concepts​

Webhook vs Polling​

Webhooks (Recommended):

  • ✅ Instant notifications
  • ✅ No API rate limits
  • ✅ Reduced server load
  • ✅ Better user experience

Polling:

  • ❌ Delayed notifications
  • ❌ Consumes API quota
  • ❌ Increased server load
  • ❌ Less efficient

Event Types​

  • TX_MINED: Transaction successfully confirmed on blockchain
  • TX_FAILED: Transaction execution failed
  • GAS_USAGE_HIGH: Gas limit warning (80%+ of limit)
  • TOKEN_TRANSFER: Token transfer event
  • TOKEN_MINT: Token mint event
  • TOKEN_BURN: Token burn event

Webhook Security​

Always verify webhook authenticity using HMAC signatures to prevent spoofing attacks.

⚠️ Important Notes​

  1. HTTPS Required: Webhook callback URLs must use HTTPS in production
  2. Status Code: Always return 2xx status code for successful processing
  3. Error Handling: Failed webhooks are retried up to 5 times with exponential backoff
  4. Signature Verification: Verify HMAC signature on all webhook requests
  5. Order Not Guaranteed: Events may arrive out of order; use timestamps

🔗 Related Endpoints​

🆘 Troubleshooting​

Webhooks Not Received​

If you're not receiving webhooks:

  • ✓ Callback URL is accessible from internet (not localhost)
  • ✓ Firewall allows incoming POST requests
  • ✓ SSL certificate is valid (for HTTPS)
  • ✓ Subscription is active (check subscription status)
  • ✓ Event types include TX_MINED and TX_FAILED

Webhook Signature Invalid​

If signature verification fails:

  • ✓ Use correct HMAC secret key
  • ✓ Include all required headers in signature calculation
  • ✓ Use correct hash algorithm (SHA-256)
  • ✓ Check for whitespace or encoding issues
  • ✓ Refer to HMAC authentication guide

Transaction Status Unknown​

If transaction status is unclear:

  • ✓ Wait for TX_MINED or TX_FAILED webhook
  • ✓ Transactions may take 1-5 minutes to mine
  • ✓ Check blockchain explorer using txHash
  • ✓ Contact support if no webhook after 15 minutes

📚 Additional Resources​

💼 Use Case Example​

Token Mint with Webhook Notification​

A platform wants to mint tokens and notify users upon completion.

Step 1 - Subscribe to Webhooks:

{
  "eventTypes": "TX_MINED",
  "callbackUrl": "https://platform.com/api/webhooks"
}

Step 2 - Mint Tokens:

{
  "to": ["0x1234567890abcdef1234567890abcdef12345678"],
  "amount": ["5000000000000000000"]
}

Response: tx_789abc...

Step 3 - Receive TX_MINED:

{
  "type": "TX_MINED",
  "event": {
    "txUUID": "tx_789abc...",
    "txHash": "0xb5c8bd...",
    "timestamp": 12345678
  }
}