Webhooks

Neutron uses webhooks to notify your server in real-time when key transaction events occur. Once configured, your webhook endpoint will receive a callback whenever a transaction reaches a terminal state (e.g., completed, expired, rejected, or error).

---

📦 Webhook Events

Webhooks are triggered only when a transaction enters a final state. These include:

Event (txnState)	Description
completed	Transaction was completed successfully
expired	Transaction expired (not confirmed/funded)
rejected	Transaction rejected due to validation errors
error	System error – manual intervention required

---

🛠 How to Set Up Webhooks

You must register a webhook endpoint using the following API:

🔧 Create a Webhook

POST /api/v2/webhook/

Headers:

{
  "Authorization": "Bearer your-access-token"
}

Body:

{
  "callback": "https://yourdomain.com/webhook",
  "secret": "your-secret-passphrase"
}

---

✏️ Update an Existing Webhook

PUT /api/v2/webhook/{webhookId}

Same headers and body format as above.

---

📬 Get Registered Webhook

GET /api/v2/webhook/

Returns a list of registered webhooks for the account.

---

❌ Delete a Webhook

DELETE /api/v2/webhook/{webhookId}

Removes the registered webhook from the account.

---

📤 Webhook Callback Payload

When triggered, Neutron sends a PUT request to your webhook URL with the following structure:

Headers:

Content-Type: application/json  
X-Neutron-Signature: <sha256-hmac-signature>

Payload:

{
  "eventId": "a1b2c3d4",
  "txnId": "41866d80-a46a-4845-a205-5cffc881cad3",
  "extRefId": "ordid-abc1234", // if provided during creation
  "txnState": "completed",
  "msg": "", // optional message
  "updatedAt": 1676030467492
}

---

🔐 Signature Verification

Neutron signs each callback with a X-Neutron-Signature header. The signature is an HMAC SHA-256 hash of the JSON body, using your webhook secret.

Signature Generation (Node.js Example):

const crypto = require("crypto");

const secret = "<your-webhook-secret>";
const payload = JSON.stringify({...}); // webhook body

const signature = crypto
  .createHmac("sha256", secret)
  .update(payload)
  .digest("hex");

Compare the computed hash to the X-Neutron-Signature header to verify authenticity.

---

🧪 Tips for Handling Webhooks

• Verify authenticity using the signature

• Acknowledge quickly by returning a 2xx response

• Avoid timeouts – process asynchronously if needed

• Retry support – Neutron may retry delivery on failure