Webhooks Guide — Real-Time Transaction Event Callbacks

Tronfuel can notify your server in real time when a transaction changes state. Webhooks are triggered during the transaction lifecycle and help your system stay in sync without polling.

---

#📍 How to Enable Webhooks

1. Go to your Tronfuel Dashboard.
2. Click the "+ Manage Webhook URLs" button.
3. Enter the desired URL where you want to receive webhook requests.
4. Optionally, generate a Webhook Secret for signed request verification.

❗️ Webhook simulation is not available yet. Use testnet (Nile) to test integration.

---

#🚦 Event Types

You will receive a webhook for one of the following event_type values:

• broadcasted: The transaction was successfully submitted to the Tron network.
• confirmed: The transaction was confirmed and included in a block.
• failed: The transaction could not be executed (e.g., out of energy, reverted contract).

ℹ️ broadcasted means the network has accepted the transaction,
but it does not guarantee that it will be confirmed.
failed means the transaction will not be included and has been rejected.

---

#📦 Webhook Payload

Webhooks are sent as POST requests with a JSON body like this:

 1{
 2  "txid": "c3b257b2d69da9355cfd2778653023edce08cf359a0ba21dfdf406303fe22bf0",
 3  "transaction_id": "01984227-e2ee-7177-9a8c-d3b7a4142904",
 4  "event_type": "confirmed",
 5  "message": "Transaction successfully confirmed on-chain.",
 6  "sender": "TRvH8C7wak5aW5jzMS7s2t1JjEYmhCBWy5",
 7  "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
 8  "price": 4.464
 9}

---

#🔐 Webhook Security: X-Signature Header

If you set a Webhook Secret, Tronfuel will sign all webhook requests using an HMAC.

• Header: X-Signature
• Algorithm: HMAC SHA256
• Base string: transaction_id from the payload
• Secret: your Webhook Secret configured in the dashboard

Signature generation logic (internal):

 1$signature = hash_hmac('sha256', $transaction_id, $secret);

Use this to verify the integrity and authenticity of incoming webhook requests.

---

#✅ How to Verify Signatures

#PHP

 1$payload = file_get_contents('php://input');
 2$data = json_decode($payload, true);
 3
 4$expected = hash_hmac('sha256', $data['transaction_id'], 'YOUR_WEBHOOK_SECRET');
 5$received = $_SERVER['HTTP_X_SIGNATURE'];
 6
 7if (hash_equals($expected, $received)) {
 8    // Process event
 9}

#Python

 1import hmac, hashlib
 2from flask import request
 3
 4data = request.get_json()
 5signature = request.headers.get("X-Signature")
 6
 7expected = hmac.new(
 8    b"YOUR_WEBHOOK_SECRET",
 9    data["transaction_id"].encode("utf-8"),
10    hashlib.sha256
11).hexdigest()
12
13if hmac.compare_digest(expected, signature):
14    # Valid webhook

#Java

 1Mac hmac = Mac.getInstance("HmacSHA256");
 2SecretKeySpec key = new SecretKeySpec("YOUR_WEBHOOK_SECRET".getBytes(), "HmacSHA256");
 3hmac.init(key);
 4
 5byte[] hash = hmac.doFinal(transactionId.getBytes());
 6String expected = Hex.encodeHexString(hash);
 7
 8if (expected.equals(receivedSignature)) {
 9    // Process webhook
10}

#Node.js

 1const crypto = require("crypto");
 2
 3function verifySignature(transactionId, signature, secret) {
 4    const expected = crypto
 5        .createHmac("sha256", secret)
 6        .update(transactionId)
 7        .digest("hex");
 8
 9    return expected === signature;
10}

#Go

 1import (
 2    "crypto/hmac"
 3    "crypto/sha256"
 4    "encoding/hex"
 5)
 6
 7func verify(transactionID, receivedSig, secret string) bool {
 8    mac := hmac.New(sha256.New, []byte(secret))
 9    mac.Write([]byte(transactionID))
10    expected := hex.EncodeToString(mac.Sum(nil))
11    return hmac.Equal([]byte(expected), []byte(receivedSig))
12}

---

#🛡 Best Practices

• Always verify the X-Signature before processing the webhook.
• Only accept HTTPS requests from known IPs or use a reverse proxy firewall.
• Log all incoming webhook attempts for auditability.
• Separate test and production secrets and URLs.
• Simulate behavior using testnet (Nile) transactions.

---

Have questions or need help debugging webhooks? Reach out to support@tronfuel.dev