Thiết lập Webhook

Webhook cho phép bạn nhận thông báo HTTPS (giao thức truyền tải siêu văn bản bảo mật) trong thời gian thực về những sự kiện trên chợ giao dịch Paxful. Ví dụ, chúng tôi có thể gửi cho bạn thông báo khi một giao dịch mới bắt đầu, hoặc bất cứ khi nào đối tác giao dịch gửi tin nhắn cho bạn trong cuộc trò chuyện giao dịch. Điều này giúp bạn không phải truy vấn API (giao diện lập trình ứng dụng) để tìm hiểu xem có thay đổi gì diễn ra hay không cũng như giúp bạn tránh đạt đến rate limit (giới hạn xử lý khối lượng đơn của hệ thống). Bản hướng dẫn này sẽ mô tả chính xác cách thiết lập Webhook với Paxful.

Chúng tôi hỗ trợ Webhook cho các sự kiện sau:

  • Giao dịch đến mới trên Paxful
  • Đã nhận tin nhắn trong cuộc trò chuyện giao dịch
  • Đã nhận tập tin đính kèm trong cuộc trò chuyện giao dịch
  • Một ai đó vừa xem hồ sơ Paxful của bạn
  • Một ai đó vừa xem đề nghị của bạn
  • Đối tác giao dịch đã thanh toán cho bitcoin của họ
  • Giao dịch bị hủy bỏ hoặc đã hết hạn
  • Bitcoin đã được bán thành công
  • Đã mua Bitcoin
  • Đã xác nhận khoản tiền gửi Bitcoin
  • Đang chờ xử lý tiền gửi bitcoin
  • Phản hồi nhận được từ một đối tác giao dịch
  • Nhận được hồi âm mới cho để lại phản hồi

Thiết lập Webhook

Ghi chú: Đảm bảo rằng dịch vụ của bạn sẵn sàng nhận Webhook. Trong quy trình lưu lại đường dẫn URL, dịch vụ của bạn cần sao chép dòng nguyên dòng request header (tiêu đề yêu cầu) "X-Paxful-Request-Challenge" và đưa vào phần response (phản hồi).

Sau đây là ví dụ về nơi mà dòng request header cần xuất hiện trong cài đặt của bạn (đây là một ví dụ về dịch vụ Webhooks trong Node.js):

RequestHeader.png

1. Truy cập vào tài khoản Paxful, di chuột tới tên đăng nhập của bạn ở phía trên bên phải trang và nhấn Cài đặt từ menu vừa xuất hiện.
ClickSettings.png

Trang Cài đặt sẽ xuất hiện.

2. Ở menu phía bên trái trang, nhấn Nhà phát triển.
Click_Developer.png

Trang Nhà phát triển sẽ xuất hiện.

3. Trong trường hợp bạn chưa có khóa API, hãy chèn mã hai yếu tố vào trường bên dưới và nhấn Thêm khóa API mới. Bạn có thể bỏ qua bước này nếu đã sở hữu khóa API.
AddAPIKey.png

Khóa API của bạn sẽ xuất hiện trên trang Nhà phát triển cùng với các mục bổ sung.

4. Sao chép URL từ ứng dụng.
Tới mục Webhook trên trang Developer của Paxful. Dán đường link vào trường Yêu cầu URL và nhấn Lưu các thay đổi.

Cảnh báo: Webhook của chúng tôi chỉ được hỗ trợ bởi loại địa chỉ HTTPS (giao thức truyền tải siêu văn bản bảo mật). Những địa chỉ HTTP (giao thức truyền tải siêu văn bản) sẽ không hỗ trợ mục đích này.


ClickSave.png

Một request header được gửi tới ứng dụng của bạn.

Lưu ý: Thơi gian chờ của chúng tôi là 10 giây. Trong trường hợp chúng tôi không nhận được phản hồi từ ứng dụng của bạn, đường dẫn URL sẽ không được lưu lại và Webhook sẽ không được khởi tạo.

5. Trong trường hợp thành công, một danh sách các sự kiện để theo dõi sẽ hiển thị như ảnh dưới đây. Tích vào ô hộp để lựa chọn từ danh sách Theo dõi các sự kiện.

Ghi chú:

  • Sau khi được chọn, các sự kiện được lưu tự động.
  • Trong trường hợp bị thất bại ba lần trong việc gửi thông tin sự kiện tới ứng dụng, Webhook (URL) sẽ bị vô hiệu hóa. 
  • Để chèn một liên kết mới, hãy thay thế đường dẫn URL hiện tại với URL mới và nhấn Thay đổi
  • Để tắt hoàn toàn Webhook, nhấn Xóa.
  • Để kích hoạt lại một đường dẫn URL đã bị tắt, nhấn Thử lại.
    ClickRetry.png

Trong trường hợp đường dẫn yêu cầu đã được lưu thành công, các sự kiện sẽ xuất hiện trong ứng dụng như sau:

WebhookexampleEvent.png

Các yêu cầu xác minh từ Paxful

Paxful tạo ra một chuỗi duy nhất cho ứng dụng và chia sẻ với bạn. Tự tin xác minh những yêu cầu từ Paxful qua xác minh chữ ký bí mật.

Trong mỗi yêu cầu HTTPS được gửi, chúng tôi thêm vào một tiêu đề HTTPS: "X-Paxful-Signature". Chữ ký được tạo ra bằng sự kết hợp giữa chữ ký bí mật với nội dung của yêu cầu, sử dụng hàm băm mật mã học tiêu chuẩn HMAC-SHA256.

Ghi chú: Chữ ký được tạo ra là duy nhất với mỗi yêu cầu và không trực tiếp chứa đựng bất cứ thông tin mật nào. Giúp bảo mật ứng dụng và ngăn ngừa những tác nhân xấu gây ra nguy hại.

Ví dụ trong JavaScript


const crypto = require('crypto');
const express = require('express');
const app = express();
const port = 3000;
const bodyParser = require('body-parser');

API bí mật từ trang https://paxful.com/account/developer:


const apiSecret = 'maE5KV16FV0nDyh7XPm2F8f8FZTdtb5p';

app.use(bodyParser.json());

Khi nhận được yêu cầu xác minh địa chỉ dịch vụ, bạn nên sao chép tiêu đề "X-Paxful-Request-Challenge" từ yêu cầu và chèn vào phần phản hồi.


app.use((req, res, next) => {

Yêu cầu xác minh địa chỉ không chứa payload (các trường lưu lại thông tin như danh tính hay quyền của người dùng) và chữ ký yêu cầu.


  if (!Object.keys(req.body).length && !req.get('X-Paxful-Signature')) {
        console.log('Address verification request received.');
        const challengeHeader = 'X-Paxful-Request-Challenge';
        res.set(challengeHeader, req.get(challengeHeader));
        res.end();
    } else {
        next();
    }
});

Khi nhận được thông báo sự kiện, bạn nên xác minh tiêu đề "X-Paxful-Signature". Không xử lý trong trường hợp yêu cầu chứa chữ kỹ sai.


  app.use((req, res, next) => {
    const providedSignature = req.get('X-Paxful-Signature');
    const calculatedSignature = crypto.createHmac('sha256', apiSecret).update(JSON.stringify(req.body)).digest('hex');
    if (providedSignature !== calculatedSignature) {
        console.log('Request signature verification failed.');
        res.status(403).end();
    } else {
        next();
    }
});

Bây giờ bạn có thể xử lý một sự kiện.


  app.post('*', async (req, res) => {
    console.log('New event received:');
    console.log(req.body);
    res.end();
});

app.listen(port, () => console.log(`Example app listening at http://localhost:${port}`));

Liên hệ với Đỗi ngũ hỗ trợ của chúng tôi trong trường hợp có bất cứ câu hỏi bổ sung nào. Bạn cũng có thể tìm hiểu thêm về dịch vụ API của chúng tôi trong tài liệu nhà phát triển.

Các bài viết trong mục này