Webhooks

Bona Fide آپ کے اینڈ پوائنٹ پر ہر اس لفافہ ایونٹ کے لیے HTTPS POST بھیجتا ہے جسے آپ نے سبسکرائب کیا ہو۔ ڈیلیوریز Standard Webhooks تفصیلات کے مطابق ہوتی ہیں، اس لیے اس کی کوئی بھی لائبریری ان کی تصدیق کر سکتی ہے۔

اینڈ پوائنٹ رجسٹر کرنا

Settings › Webhooks میں، یا ایسی API کلید سے جس کے پاس org:manage اسکوپ ہو:

curl https://api.bonafidesign.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/hooks/bona-fide",
    "description": "Production",
    "events": ["envelope.completed", "envelope.sealed", "envelope.declined"]
  }'

جواب میں secret (whsec_…) شامل ہوتا ہے، صرف اسی ایک بار۔ خالی events فہرست ہر ایونٹ کو سبسکرائب کرتی ہے۔ URL کا عوامی https:// ہونا ضروری ہے۔ اینڈ پوائنٹ ایک ہی موڈ سے تعلق رکھتا ہے: ٹیسٹ کلید سے بنائے گئے اینڈ پوائنٹس صرف ٹیسٹ موڈ کے لفافوں کے ایونٹس وصول کرتے ہیں، اور لائیو اینڈ پوائنٹس صرف لائیو ایونٹس۔

PATCH /v1/webhook-endpoints/{id} URL، ایونٹس یا تفصیل بدلتا ہے اور اینڈ پوائنٹ کو روکتا یا دوبارہ شروع کرتا ہے (enabled)۔ POST /v1/webhook-endpoints/{id}/test ایک webhook.test پنگ بھیجتا ہے۔

ایونٹس

قسم	کب
envelope.created	لفافہ بنا دیا گیا
envelope.ready	دستاویز رینڈر ہو گئی اور لفافہ اپنے وصول کنندگان کے لیے تیار ہے
recipient.sent	کسی وصول کنندہ کی باری آ گئی (اور، ای میل ڈیلیوری کے ساتھ، اس کا لنک بھیج دیا گیا)
recipient.viewed	کسی وصول کنندہ نے پہلی بار دستخط کا صفحہ کھولا
recipient.signed	کسی وصول کنندہ نے جمع کرا دیا (یا خودکار طور پر جوابی دستخط ہو گئے)
recipient.declined	کسی وصول کنندہ نے انکار کر دیا
envelope.completed	ہر وصول کنندہ نے کام مکمل کر لیا۔ data.values میں ویری ایبلز اور ہر ٹائپ کی گئی ویلیو ہوتی ہے
envelope.sealed	سیل شدہ PDF ڈاؤن لوڈ کے لیے تیار ہے
envelope.declined	لفافہ اس لیے ختم ہوا کہ کسی وصول کنندہ نے انکار کر دیا
envelope.voided	آپ نے لفافہ کالعدم کر دیا
envelope.expired	تکمیل سے پہلے expiresAt گزر گیا
signing_link.used	کسی وزیٹر نے ہمیشہ فعال دستخط کے لنک سے لفافہ شروع کیا

acceptance.created اسکیما میں محفوظ ہے اور ابھی جاری نہیں کیا جاتا۔

پے لوڈ

{
  "id": "evt_9sKq2Lm4Tz",
  "type": "envelope.completed",
  "createdAt": "2026-10-13T14:09:52.004Z",
  "testMode": false,
  "data": {
    "envelope": {
      "id": "env_8Gm2kQ4rT1",
      "status": "completed",
      "seal": "pending",
      "recipients": [{ "id": "rcp_5Jw0pLs9Xe", "role": "client", "status": "completed", "…": "…" }],
      "externalId": "user_8841",
      "metadata": {},
      "…": "…"
    },
    "values": {
      "variables": { "client": { "name": "Acme Robotics, Inc." }, "effective_date": "2026-10-13" },
      "recipients": {
        "client": { "client_title": "CEO", "start_date": "2026-11-01" }
      }
    }
  }
}

data.envelope ایونٹ کے وقت کا مکمل لفافہ ہے۔ data.values صرف envelope.completed پر ہوتا ہے: آپ کے بھیجے گئے ویری ایبلز، اور ہر کردار کی فیلڈ ویلیوز فیلڈ id کے مطابق۔

ہیڈرز اور دستخط

ہر ڈیلیوری میں یہ ہوتے ہیں:

ہیڈر	ویلیو
webhook-id	ایونٹ کی id (evt_…)؛ ہر ری ٹرائی پر یکساں۔ ڈپلیکیٹ سے بچنے کے لیے اسے استعمال کریں
webhook-timestamp	Unix سیکنڈز جب اس کوشش پر دستخط ہوئے
webhook-signature	v1,<base64 HMAC-SHA256>، جب ایک سے زیادہ سیکرٹس دستخط کریں تو خالی جگہ سے الگ
user-agent	BonaFide-Webhooks/1

دستخط {webhook-id}.{webhook-timestamp}.{raw body} پر HMAC-SHA256 ہے، جس کی کلید سیکرٹ میں whsec_ کے بعد والا base64-decoded حصہ ہے۔ خام باڈی کی تصدیق کریں (JSON پارسنگ سے پہلے)، موازنہ constant time میں کریں، اور ایسے ٹائم اسٹیمپس مسترد کریں جو آپ کی گھڑی سے پانچ منٹ سے زیادہ دور ہوں۔

TypeScript

import express from 'express';
import { Webhook } from 'standardwebhooks'; // npm i standardwebhooks

const wh = new Webhook(process.env.BONA_FIDE_WEBHOOK_SECRET!); // whsec_…
const app = express();

app.post('/hooks/bona-fide', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers as Record<string, string>); // throws if forged or too old
  } catch {
    return res.sendStatus(400);
  }
  queue.add(event); // do the work asynchronously and answer quickly
  res.sendStatus(204);
});

Python

# pip install standardwebhooks flask
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["BONA_FIDE_WEBHOOK_SECRET"])  # whsec_…
app = Flask(__name__)

@app.post("/hooks/bona-fide")
def bona_fide():
    try:
        event = wh.verify(request.get_data(), dict(request.headers))
    except Exception:
        return "", 400
    enqueue(event)
    return "", 204

Node (بغیر لائبریری)

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret: string, headers: Record<string, string>, rawBody: string) {
  const id = headers['webhook-id'];
  const ts = Number(headers['webhook-timestamp']);
  if (!id || !ts || Math.abs(Date.now() / 1000 - ts) > 300) throw new Error('stale or missing headers');
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest();
  const ok = (headers['webhook-signature'] ?? '').split(' ').some((part) => {
    const [version, sig] = part.split(',');
    const given = Buffer.from(sig ?? '', 'base64');
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
  });
  if (!ok) throw new Error('bad signature');
  return JSON.parse(rawBody);
}

ری ٹرائز

ڈیلیوری 10 سیکنڈ کے اندر کسی بھی 2xx پر کامیاب ہوتی ہے۔ ری ڈائریکٹس پر عمل نہیں کیا جاتا۔ باقی سب کی دوبارہ کوشش بڑھتے وقفوں کے ساتھ ہوتی ہے: 5 سیکنڈ، 5 منٹ، 30 منٹ، 2 گھنٹے، 5 گھنٹے، 10 گھنٹے، 14 گھنٹے، 20 گھنٹے اور 24 گھنٹے بعد، ایونٹ کے بعد زیادہ سے زیادہ تین دن تک۔ اس کے بعد ڈیلیوری ناکام قرار دی جاتی ہے۔

• جلدی جواب دیں اور کام غیر ہم وقت طور پر کریں؛ webhook-id کی بنیاد پر ڈپلیکیٹ ختم کریں۔
• ڈیلیوریز بے ترتیب پہنچ سکتی ہیں: کسی ترتیب کو فرض کرنے کے بجائے data.envelope.status چیک کریں۔
• GET /v1/webhook-endpoints/{id}/deliveries حالیہ کوششوں کو اسٹیٹس کوڈز، ایررز اور اوقات کے ساتھ دکھاتا ہے، اور ہر اینڈ پوائنٹ اپنی 24 گھنٹے کی کامیابی کی شرح (health) دکھاتا ہے۔
• POST /v1/events/{id}/redeliver کسی ایونٹ کو اینڈ پوائنٹ پر دوبارہ بھیجتا ہے، مثلاً کسی تعطل کے بعد۔

سیکرٹ تبدیل کرنا

POST /v1/webhook-endpoints/{id}/secret/rotate فوراً نیا سیکرٹ واپس کرتا ہے۔ اگلے 24 گھنٹوں تک ہر ڈیلیوری پر نئے اور پرانے دونوں سیکرٹس سے دستخط ہوتے ہیں (webhook-signature میں دو اندراجات)، اس لیے آپ ایونٹس کھوئے بغیر نیا سیکرٹ ڈیپلائے کر سکتے ہیں۔

احتیاط

سیکرٹ کو پاس ورڈ کی طرح محفوظ رکھیں۔ جس کے پاس یہ ہو وہ ایسی جعلی ڈیلیوریز بنا سکتا ہے جو تصدیق میں کامیاب ہو جائیں۔