🚀 Connect Webhook

Webhooks allow your application to receive real-time updates for specific events occurring on the 1buy.io platform. By configuring a webhook, you can automate tasks such as order processing, transaction tracking, and customer notifications.

Setting Up the Webhook

Step 1: Register the Webhook URL

Navigate to the Dashboard:
- Development Environment → https://dev.1buy.io/widget-webhook
- Production Environment → https://app.1buy.io/widget-webhook
Go to the Webhook Settings section in your dashboard.
Enter the URL where you want to receive the webhook payloads.
- Example: https://yourdomain.com/webhook-endpoint.
Click Save to register the webhook URL.

Note: Ensure your webhook URL is publicly accessible and supports HTTPS.

Step 2: Catching the Webhook Response

To handle webhook events, you need to set up a server endpoint that listens for POST requests.

Steps:

Create an Endpoint: Create a new endpoint in your server application that listens for POST requests.
Receive Payload: The webhook data will be sent in the req.body of the POST request. Ensure your server can parse JSON payloads.

Example in Node.js:

const express = require("express");
const app = express();

app.use(express.json()); // Middleware to parse JSON payloads

app.post("/my-webhook-endpoint", (req, res) => {
  const webhookPayload = req.body;
  console.log("Received webhook:", webhookPayload);

  // Process the webhook data
  res.status(200).send("Received!");
});

app.listen(3000, () => {
  console.log("Webhook server is running on port 3000");
});

Webhook Response Structure

When a webhook triggers, it sends a JSON response with the following structure:

{
  "data": {
    "id": "string", // Order ID
    "custom_id": "string", // Your custom identifier to track customers
    "user_id": "string", // User ID on the platform
    "product_id": "string", // Your Product ID
    "type": "string", // Event type (e.g., payment_started, order_complete)
    "base": "string", // Crypto Currency used
    "base_amount": "string", // Crypto Amount
    "quote": "string", // Fiat Currency used
    "quote_amount": "string", // Fiat Amount
    "address": "string", // Wallet Address
    "transaction_id": "string", // Blockchain transaction ID
    "partner_data": "object",
    "full_name": "string",
    "date_of_birth": "string",
    "phone": "string",
    "email": "string",
    "state": "string",
    "country": "string",
    "city": "string",
    "street": "string",
    "postal_code": "string",
    "utm_source": "string",
    "clickID": "string",
    "campaignID": "string",
    "fail_reason": "string",
    "redirect_url": "string",
    "fail_redirect_url": "string",
    "redirect_page": "string",
    "external_user_id": "strung" // User Id you can use to fetch user details For more details check API References > User Creation & Detail API
  }
}

Response Fields

Field	Type	Description
`id`	`string`	Order ID.
`custom_id`	`string`	Your custom identifier to track your customers.
`user_id`	`string`	User ID associated with the transaction.
`product_id`	`string`	Product ID of the associated product.
`type`	`string`	Order status (e.g., `payment_started`, `order_complete`, `order_failed`, etc.).
`base`	`string`	Cryptocurrency used for the transaction.
`base_amount`	`string`	Amount of cryptocurrency used.
`quote`	`string`	Fiat currency used for the transaction.
`quote_amount`	`string`	Amount of fiat currency used.
`address`	`string`	Wallet address used for the transaction.
`transaction_id`	`string`	Blockchain transaction ID.
`partner_data`	`object`	Data related to the blueprint address and input.
`full_name`	`string`	Full name of the user.
`date_of_birth`	`string`	Date of birth of the user.
`phone`	`string`	Phone number of the user.
`email`	`string`	Email address of the user.
`state`	`string`	State of the user.
`country`	`string`	Country of the user.
`city`	`string`	City of the user.
`street`	`string`	Street of the user.
`postal_code`	`string`	Postal Code of the user.
`utm_source`	`string`	UTM source for tracking.
`clickID`	`string`	Click ID for tracking.
`campaignID`	`string`	Campaign ID for tracking.
`fail_reason`	`string`	Reason for transaction failure, if applicable.
`redirect_url`	`string`	URL to redirect after successful transaction.
`fail_redirect_url`	`string`	URL to redirect after a failed transaction.
`redirect_page`	`string`	Specifies how the redirect happens (`new` or `self`).

Events

The webhook triggers for the following events:

Event Type	Description
`link_unopened`	Default event when your checkout URL is one-time hashed and hasn't been opened yet.
`link_opened`	Triggered when the one-time hashed checkout URL is accessed by the user.
`payment_started`	Triggered when users reach the confirm purchase page.
`payment_initiated`	Triggered when the payment process is initiated.
`order_complete`	Triggered when an order is successfully completed.
`order_failed`	Triggered when an order fails (e.g., due to payment issues).
`transfer_started`	Triggered when a fund transfer to the wallet begins.
`order_canceled`	Triggered when an order received “Cancelled” status.
`refund_processed`	Triggered when a refund is successfully processed.
`tx_smart_contract_failed`	Triggered when a transaction to the smart contract has failed.

Error Codes

Below are the possible error codes and their meanings, sent when a transaction fails:

Error Code	Error Meaning
4000	We weren't able to charge the user's card, and the order was not completed. The user can try again.
4001	The transaction failed due to an incorrect CVV/CVC. The user should re-enter the correct CVV/CVC.
4002, 4010, 4012	Payment was declined by the card issuer. The user should contact their card issuer for further details.
4003	Incorrect card details were provided. The user should re-enter valid card details.
4004	Insufficient balance on the card. The user should add funds and try again.
4005	The card limit was exceeded. The user should use a different card to complete the purchase.
4011	Card validation failed. The user should provide a valid card.
4013	We weren't able to charge the user's card, and the order was not completed. The user should contact support for assistance.

Webhook Security

To ensure secure communication between your application and 1buy.io, follow these best practices:

Use HTTPS

Always use HTTPS for your webhook URL to encrypt data in transit and ensure secure communication.

Ensure POST Requests

Your webhook endpoint should only accept POST requests to avoid unauthorized access or invalid requests.
Reject any requests that do not use the POST method with an appropriate HTTP status code (e.g., 405 Method Not Allowed).

Respond with 200 OK

Ensure your webhook endpoint responds with a 200 OK status code to acknowledge successful processing of the event.

Log Events

Log all incoming webhook events for debugging and auditing purposes.
Maintain detailed records of webhook interactions to assist with troubleshooting and compliance.

Troubleshooting

Not Receiving Webhooks?

Ensure that the webhook URL is correctly configured in the dashboard.
Verify that your server is accessible from the internet and properly configured to receive POST requests.
Check your server logs for incoming requests or errors.

Invalid Data?

Validate the structure of the webhook payload.
Confirm that your server is correctly parsing the JSON data from the POST request.

🚀 Connect Webhook

Setting Up the Webhook​

Step 1: Register the Webhook URL​

Step 2: Catching the Webhook Response​

Steps:​

Example in Node.js:​

Webhook Response Structure​

Response Fields​

Events​

Error Codes​

Webhook Security​

Use HTTPS​

Ensure POST Requests​

Respond with 200 OK​

Log Events​

Troubleshooting​

Not Receiving Webhooks?​

Invalid Data?​