வலைப்பின்னல் மாதிரிகள், developers அதிகமாக கேட்கின்றனர்.
ஒரு நம்பகமான webhook கையாளுநர் வரிசைப்படி நான்கு விஷயங்களை செய்கிறது: கையொப்பத்தை RAW உடலுக்கு எதிராக சரிபார்க்கவும் (Node இல் webhooks.verify, மற்ற இடங்களில் ஆவணப்படுத்தப்பட்ட HMAC), நிகழ்வு ஐடியால் மீண்டும் உருவாக்கவும், பின்னணி வரிசைக்கு வேலை enqueue செய்யவும், மற்றும் 200 ஐ வழங்கவும். நீண்டகால வேலை வேலைக்காரத்தில் நடைபெறும், மீண்டும் முயற்சிகள் மற்றும் வரிசை அடிப்படையில் ஒரே மாதிரியான செயல்பாடுகளுடன். தோல்வி நிகழ்வு இல்லாததால், திட்டமிடப்பட்ட சுத்திகரிப்பு பணிகளை செலுத்துவதற்காக காத்திருக்கும் பணிகளை நேரம் கடந்து விடுகிறது மற்றும் அவற்றை சமரசம் செய்கிறது.
நீங்கள் தொடங்குவதற்கு முன்.
- செயல்படும் முகவர் சுயவிவரம் மற்றும் உங்கள் டாஷ்போர்டில் இருந்து கையொப்ப ரகசியம் (அமைப்புகள் - Webhooks).
- ஒரு மொத்த உடல் அணுகலுடன் கூடிய வலை கட்டமைப்பு -
express.rawஉடன் Express, FastAPI, Flask, மற்றும் பிற. தானாகவே JSON மிட்ல்வேரில் கையொப்பத்தை சரிபார்க்கிறது. - ஒரு வேலை வரிசை: BullMQ (Node) அல்லது Celery/arq (Python). Webhook 200 விரைவாக திருப்புகிறது மற்றும் வரிசை மெதுவான வேலை செய்கிறது.
- ஒரு upsert அடிப்படையுடன் ஒரு தரவுத்தளம் (Postgres வேலை செய்கிறது; குறுகிய காலம் கொண்ட மறுபடியும் உருவாக்கத்திற்காக Redis SET NX வேலை செய்கிறது).
- ஒரு பொது HTTPS முடிவுக்குறி - மேம்பாட்டில், ngrok அல்லது ஒரு வெளியீட்டு முன்னோட்டம். அனுப்புபவர் தனிப்பட்ட URL க்கு வழங்காது.
கையொப்பத்தை உறுதிப்படுத்தவும்.
The signature is HMAC-SHA256 over {t}.{rawBody} with your webhook secret, hex-encoded, in the X-Blockchain0x-Signature header (t=<unix>,v1=<hex>), inside a 5-minute replay window. In Node, webhooks.verify from @blockchain0x/node does it and returns a discriminated union; in other languages compute the same HMAC and compare in constant time. Raw-body access matters: if the bytes you sign locally differ from the bytes that arrived, it fails.
import express from "express";
import { webhooks } from "@blockchain0x/node";
const app = express();
// Raw body so the HMAC matches the exact bytes on the wire.
app.use(express.raw({ type: "application/json" }));
app.post("/webhooks/payment", (req, res) => {
const result = webhooks.verify({
headers: req.headers,
rawBody: req.body, // Buffer, raw bytes
secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!,
});
// Discriminated union: branch on ok, no try/catch.
if (!result.ok) return res.status(400).json({ code: result.code });
// result.eventType / result.eventId are now set.
handleEvent(result);
res.status(200).send("ok");
});import hmac, hashlib, os, time
from flask import request
SECRET = os.environ["BLOCKCHAIN0X_WEBHOOK_SECRET"].encode()
# In Node, webhooks.verify does this. In Python, verify by hand against the
# documented algorithm: HMAC-SHA256 over "{t}.{rawBody}", 300s replay window.
def verify_signature(raw_body: bytes) -> bool:
sig = request.headers.get("X-Blockchain0x-Signature", "")
ts = request.headers.get("X-Blockchain0x-Timestamp", "")
parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
t, v1 = parts.get("t", ts), parts.get("v1", sig)
want = hmac.new(SECRET, t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(want, v1) and abs(time.time() - int(t)) <= 300கையாளரை ஒரே மாதிரியானதாக உருவாக்கவும்.
Webhooks retry on any non-2xx response, and the same event will arrive multiple times under load even when nothing has gone wrong. Dedupe on the event's id using a database upsert. If the row already exists, skip; if it does not, insert and proceed. Postgres makes this a single statement.
// Pseudocode for a Postgres-backed dedupe table. Replace with your DB of choice.
async function processEventOnce(eventId: string, body: object) {
// INSERT ... ON CONFLICT DO NOTHING returns rowCount === 0 on duplicate.
const inserted = await db.query(
"INSERT INTO webhook_events(id) VALUES ($1) ON CONFLICT DO NOTHING",
[eventId],
);
if (inserted.rowCount === 0) return; // Already processed.
await handleEvent(body);
}async def process_event_once(event_id: str, body: dict):
# INSERT ... ON CONFLICT DO NOTHING returns 0 rows on duplicate.
inserted = await db.execute(
"INSERT INTO webhook_events (id) VALUES ($1) ON CONFLICT DO NOTHING",
event_id,
)
if inserted == "INSERT 0 0": # asyncpg-style status
return # Already processed.
await handle_event(body)என்க்யூ மற்றும் 200 விரைவாக திருப்பவும்.
வலைப்பின்னல் இறுதிக்குறிப்பு ஒரு விநாடிக்குள் பதிலளிக்க வேண்டும். எதுவும் மெதுவாக இருந்தால், நேரத்திற்குள் முடிவுகள் மற்றும் மீண்டும் முயற்சிகள் வரவேற்கின்றன. மாதிரி: சரிபார்க்கவும், வரிசைப்படுத்தவும், பதிலளிக்கவும். வரிசை மீண்டும் முயற்சிகள், எக்ஸ்போனென்ஷியல் பின்வாங்குதல் மற்றும் அதன் சொந்த அடிப்படையை உள்ளடக்கிய ஒரு பணியாளருக்குள் உண்மையான வழங்கலை இயக்குகிறது. BullMQ மற்றும் Celery இரண்டும் ஒவ்வொரு வேலை ID க்கும் ஆதரவு வழங்குகின்றன, இது ஒரே நிகழ்வின் மீண்டும் வரிசைப்படுத்துதலைத் தவிர்க்கிறது.
// Express handler: verify, enqueue, return 200 fast.
import { Queue } from "bullmq";
import { webhooks } from "@blockchain0x/node";
const paymentQueue = new Queue("payments");
app.post(
"/webhooks/payment",
express.raw({ type: "application/json" }),
async (req, res) => {
const result = webhooks.verify({
headers: req.headers,
rawBody: req.body,
secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!,
});
if (!result.ok) return res.status(400).json({ code: result.code });
await paymentQueue.add(result.eventType, { raw: req.body.toString() }, {
jobId: result.eventId, // Idempotency key.
removeOnComplete: true,
attempts: 5,
backoff: { type: "exponential", delay: 1000 },
});
res.status(200).send("ok");
},
);
// Worker file:
import { Worker } from "bullmq";
new Worker("payments", async (job) => {
await handleEvent(job.data);
});# Flask handler enqueues to Celery (or arq) and returns 200 quickly.
from celery import Celery
from flask import request
celery = Celery("payments", broker=os.environ["REDIS_URL"])
@celery.task(bind=True, max_retries=5)
def handle_payment_event(self, event_type, raw):
try:
process_event_once(event_type, raw)
except Exception as exc:
raise self.retry(exc=exc, countdown=2 ** self.request.retries)
@app.post("/webhooks/payment")
def webhook():
raw = request.get_data()
if not verify_signature(raw):
abort(401)
event_id = request.headers.get("X-Blockchain0x-Event-Id", "")
event_type = request.headers.get("X-Blockchain0x-Event-Type", "")
handle_payment_event.apply_async(args=[event_type, raw.decode()], task_id=event_id)
return "ok", 200arq Python பக்கம் ஒரே வடிவத்தை பின்பற்றுகிறது - ஒரு தீர்மானமான வேலை id உடன் பணியை பதிவு செய்யவும் மற்றும் வரிசை மீண்டும் முயற்சிகளை கையாள அனுமதிக்கவும். முக்கிய கட்டுப்பாடு வரிசைப்படுத்தல் வேகமாக இருக்க வேண்டும் (Redis க்கு ஒரு சுற்று பயணம்); தொலைதூர அழைப்புகளில் வெப்குக் தடுப்பதில்லை.
எப்போதும் விழாத செலுத்தலை கையாளுங்கள்.
தவறு webhook இல்லை - ஒரு வாங்குபவர் விலகினால், எந்த நிகழ்வும் வராது, மற்றும் முகவர் 'பணம் காத்திருக்கிறது' என்ற நிலையில் சிக்கி விடுகிறது. எனவே, அதை நீங்கள் தானாகவே கண்டறியுங்கள்: மிகவும் நீண்ட நேரம் காத்திருந்த வேலைகளின் மீது ஒரு திட்டமிட்ட சுத்தம் இயக்கவும், அது உண்மையில் தீர்வு பெற்றால் transactions.get உடன் சங்கிலிக்கு எதிராக சமன்வயம் செய்யவும், பிறகு பிடிக்கப்பட்ட வளங்களை விடுவிக்கவும், வேலைக்கு ஒரு இறுதி செலவில்லா நிலையில் நகர்த்தவும், மற்றும் (தேவையானால்) பயனருக்கு முடிவை வெளிப்படுத்தவும்.
async function sweepStaleAwaitingPayment() {
for (const job of await findJobsAwaitingPaymentOlderThan("1h")) {
// Reconcile against the chain before giving up.
const tx = job.txHash ? await client.transactions.get(job.txHash) : null;
if (tx) { markJobPaid(job.id); continue; } // It actually settled.
// 1. Release any held resources tied to the job.
releaseHeldResources(job.id);
// 2. Move it out of 'awaiting_payment' into a terminal 'unpaid' state.
markJobUnpaid(job.id);
// 3. (Optional) Notify the user, with a fresh payment link.
notifyUser(job.userId, { template: "agent_payment_unpaid", jobId: job.id });
}
}# Run on a schedule - there is no failure webhook to wait for.
def sweep_stale_awaiting_payment():
for job in find_jobs_awaiting_payment_older_than("1h"):
tx = client.transactions.get(job["tx_hash"]) if job.get("tx_hash") else None
if tx:
mark_job_paid(job["id"]) # It actually settled.
continue
release_held_resources(job["id"])
mark_job_unpaid(job["id"])
notify_user(job["user_id"], template="agent_payment_unpaid", job_id=job["id"])நிகழ்வுகளை தவிர்க்கும் அல்லது நகலெடுக்கிற ஐந்து தவறுகள்.
கையொப்பத்தை சரிபார்க்கும் முன் உடலை பகுப்பாய்வு செய்தல்
HMAC ஐ அனுப்புநர் கையொப்பமிட்ட கச்சா பைட்டுகள் மீது கணக்கிட வேண்டும். உங்கள் கட்டமைப்பு உங்கள் கையாளுனர் இயங்குவதற்கு முன் JSON ஐ தானாகவே பகுப்பாய்வு செய்யும் என்றால், நீங்கள் உள்ளூர் அளவில் கையொப்பமிடும் பைட்டுகள் அனுப்புநர் கையொப்பமிட்ட பைட்டுகளுடன் பொருந்தாது (வித்தியாசமான வெள்ளை இடங்கள், விசை வரிசை, குறியீடு) மற்றும் ஒவ்வொரு கையொப்பமும் தவறானதாக தோன்றும். கச்சா உடலைப் பெறுவதற்கான வழியை அமைக்கவும் (Express: express.raw, Flask: request.get_data), முதலில் சரிபார்க்கவும், பின்னர் பகுப்பாய்வு செய்யவும்.
Webhook கையாளரின் உள்ளே உண்மையான வேலை செய்யுதல்
Webhook கையாளிகள் தீவிரமான மீண்டும் முயற்சி கொள்கைகளை கொண்டுள்ளன. உங்கள் கையாளுநர் வேலை வழங்க 30 நொடிகள் எடுத்தால், அனுப்புநரின் காலாவதியானது செயல்படுகிறது மற்றும் webhook மீண்டும் அனுப்பப்படுகிறது - இப்போது நீங்கள் ஒரே கட்டணத்திற்கான இரண்டு வழங்கல்களைக் கொண்டுள்ளீர்கள். எப்போதும்: சரிபார்க்கவும், வரிசைப்படுத்தவும், 2xx ஐ திரும்பவும். உண்மையான வேலை தேவையான அளவுக்கு எவ்வளவு நேரம் எடுத்துக்கொள்கிறது என்பதைக் கொண்ட ஒரு பின்னணி பணியாளரின் உள்ளே செயல்படுகிறது.
வணிக உளவியல் தொடர்பு கொள்ள HTTP நிலையைப் பயன்படுத்துதல்
உங்கள் கையாளுநர் 4xx ஐ திருப்பினால், பயனர் உங்கள் அமைப்பில் இனி இல்லாத போது, அனுப்புநர் அதை 'தவறான கோரிக்கை' என்று கருதுகிறது மற்றும் மீண்டும் முயற்சிக்க stops. அதே நிலைக்கு 5xx ஐ திருப்பினால், அனுப்புநர் எப்போதும் மீண்டும் முயற்சிக்கிறது மற்றும் உங்கள் வரிசை நிரம்புகிறது. நீங்கள் நிகழ்வைப் பாதுகாப்பாக நிலைத்திருக்கும்போது (அல்லது அதை நகலாக அடையாளம் காணும்போது) 200 ஐ திருப்புங்கள்; வணிக முடிவுகளை வெளிப்படுத்த queue தரவியல், HTTP நிலை அல்ல.
நிகழ்வு ID க்கு பதிலாக payload hash இல் Idempotency
அதே முகவரியைப் பற்றிய இரண்டு வெவ்வேறு நிகழ்வுகள் (ஒரு payment.received மற்றும் பின்னர் payment.sent) வெவ்வேறு உடல்களை கொண்டுள்ளன மற்றும் சட்டப்படி தனித்தனியாக செயலாக்கம் தேவை. உங்கள் dedupe ஒரு உடல் ஹாஷில் இருந்தால், நீங்கள் அவற்றில் ஒன்றை விடலாம். X-Blockchain0x-Event-Id (ஒவ்வொரு விநியோகத்திற்கும் தனித்துவமான) இல் dedupe செய்யவும், மற்றும் நிகழ்வு வகை உங்கள் கைப்பற்றல் என்ன செய்கிறது என்பதை இயக்க அனுமதிக்கவும்.
தனித்துவமான உறுதிப்படுத்தல் நிகழ்வை எதிர்பார்க்கிறேன்
அனுப்பப்பட்ட நிகழ்வுகள் payment.received, payment.sent, wallet.deployed, மற்றும் webhook.test ஆக உள்ளன - தனித்துவமான உறுதிப்படுத்தல் நிகழ்வு இல்லை. பரிமாற்றம் ஒரு தொகுதியில் இருக்கும் போது payment.received செயல்படுகிறது, இது உங்கள் பெரும்பாலான வேலைக்கு சிக்னல் ஆகும். விலை உயர்ந்த அல்லது திருப்பமுடியாத ஒன்றிற்காக, transactions.get ஐ கண்காணிக்கவும் மற்றும் உங்கள் சொந்த உறுதிப்படுத்தல் அளவுகோலைப் பயன்படுத்தவும்; இல்லாத நிகழ்விற்காக காத்திருக்காதீர்கள்.
ஒரு முறை வெப் ஹூக்கள் புல்லெட் புரூஃப் ஆகும்.
Webhooks என்பது கடினமான பகுதி. மேலே உள்ள நான்கு மாதிரிகள் உள்ளதால், மீதமுள்ள வேலை பெரும்பாலும் செயல்பாட்டில் உள்ளது: தோல்வி பாதைகளை பயிற்சி செய்யும் ஒரு சோதனை சூழல், மேல்நிலை முகவர் உங்கள் கையாள்பவரை வெள்ளமாக்காத வகையில் செலவுப் கட்டுப்பாடுகள், மற்றும் இறுதி பாதுகாப்பு மதிப்பீடு.
உண்மையான பணம் இல்லாமல் முகவர் கட்டணங்களை சோதிக்கவும்
உரை ஊடுருவலைத் தாண்டும் முகவர் செலவுகளை கட்டுப்படுத்தவும்
நேரில் செல்லும் முன் உங்கள் முகவர் காப்பகத்தை பாதுகாப்பாக வைக்கவும்
முழு குறிப்புகள் docs.blockchain0x.com இல் உள்ளன. வலைப்பதிவு அகராதி: கட்டண ஆணை. தயாரிப்பு மேற்பரப்பு: கட்டண API.