curl --request POST \
--url https://api.ayrshare.com/api/hook/webhook/secret \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Profile-Key: YOUR_PROFILE_KEY' \
--data '{
"secret": "your-new-signing-secret"
}'
{
"status": "success",
"action": "webhook",
"refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}
Webhooks
Rotate Signing Secret
24-घंटे dual-signing grace window के साथ अपने webhook signing secret को सुरक्षित रूप से rotate करें
POST
/
hook
/
webhook
/
secret
curl --request POST \
--url https://api.ayrshare.com/api/hook/webhook/secret \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Profile-Key: YOUR_PROFILE_KEY' \
--data '{
"secret": "your-new-signing-secret"
}'
{
"status": "success",
"action": "webhook",
"refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}
Overview
Ayrshare हर webhook delivery को payload के HMAC-SHA256 से sign करता है, जो आपके signing secret द्वारा keyed होता है, ताकि आपका receiver पुष्टि कर सके कि delivery वास्तव में Ayrshare से आई है। सत्यापन कैसे काम करता है, इसके लिए Webhook Security देखें। अपने signing secret को rotate करने से आप इसे नियमित रूप से, या यदि आपको संदेह है कि यह उजागर हो गया है तो तुरंत बदल सकते हैं। Rotation को सुरक्षित बनाने के लिए, Ayrshare हर rotation के बाद एक 24-घंटे का grace window खोलता है जिसके दौरान deliveries आपके पिछले और आपके नए secret दोनों से signed होती हैं। यह आपको एक भी delivery को drop या reject किए बिना अपने receiver को अपने शेड्यूल पर अपडेट करने देता है — वही pattern जो Stripe और GitHub उपयोग करते हैं।Signing secret profile-wide होता है: प्रति User Profile (UID) एक secret होता है,
और यह उस profile ने जो हर webhook action रजिस्टर किया है, उसे sign करता है। कोई
per-action signing secret नहीं है — secret को सेट या rotate करने से उस profile के सभी
actions के लिए यह एक साथ बदल जाता है।
Dashboard से Rotate करें
आप Developer Dashboard में Webhooks page से अपने signing secret को सेट या rotate कर सकते हैं। Signing Secret panel आपकी webhook सूची के ऊपर तब दिखाई देता है जब profile में कम से कम एक रजिस्टर किया गया webhook हो।1
Signing Secret panel खोलें
Webhooks page पर जाएँ। यदि अभी तक कोई secret configured नहीं है, तो panel No signing secret configured एक Set Signing Secret बटन के साथ दिखाता है। यदि एक पहले से configured है, तो यह Signing secret configured एक Rotate बटन के साथ दिखाता है।
2
Set या Rotate
Set Signing Secret (पहली बार) या Rotate (मौजूदा secret) पर क्लिक करें। एक modal खुलता है जिसमें एक strong, यादृच्छिक रूप से जनरेट किया गया secret pre-filled और प्रकट होता है। आप इसे Copy कर सकते हैं, एक नया Regenerate कर सकते हैं, या अपना स्वयं का मान देने के लिए paste my own को टॉगल कर सकते हैं।
3
Confirm
Secret को कहीं सुरक्षित स्थान पर कॉपी करें — इसे केवल एक बार दिखाया जाता है और इसे UI से फिर कभी पुनः प्राप्त नहीं किया जा सकता — फिर submit करने के लिए confirm करें। एक success toast दिखाई देता है और panel अपडेट हो जाता है।
4
अपने receiver को अपडेट करें
Rotation पर (पहली बार सेट नहीं), panel एक active grace-window indicator दिखाता है और Rotate बटन तब तक disabled रहता है जब तक window बंद नहीं हो जाती। आपके पास नए secret को अपने receiver पर डिप्लॉय करने के लिए 24 घंटे हैं।
API के माध्यम से Rotate करें
एकल कॉल के साथ signing secret को rotate (या set) करें। यह एक नया secret बनाता है, profile के secret reference को इस पर repoint करता है, और — जब एक मौजूदा secret था — supersede किए गए secret को 24 घंटे बाद expiry के साथ previous secret के रूप में रिकॉर्ड करता है।Header Parameters
Body Parameters
string
आवश्यक
नया signing secret मान। कोई भी non-empty string स्वीकार किया जाता है। हम एक long, high-entropy random मान की सिफारिश करते हैं (उदाहरण के लिए, base64url के रूप में एन्कोड किए गए 32 random bytes)।
curl --request POST \
--url https://api.ayrshare.com/api/hook/webhook/secret \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Profile-Key: YOUR_PROFILE_KEY' \
--data '{
"secret": "your-new-signing-secret"
}'
{
"status": "success",
"action": "webhook",
"refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}
secret कभी भी response में नहीं लौटाया जाता और कभी log नहीं किया जाता। Response में client-facing refId (UID का एक hash) होता है, कभी भी UID स्वयं नहीं। Profile-Key header वैकल्पिक है और multi-profile accounts के लिए rotation को एकल User Profile तक सीमित करता है।
एक missing या empty secret एक mapped error (code: 101, “Missing/incorrect parameter”) HTTP 400 status के साथ लौटाता है, और आपके वर्तमान secret में कोई परिवर्तन नहीं किया जाता। API के माध्यम से पहली बार सेट (कोई मौजूदा secret नहीं) बिना कोई previous secret रिकॉर्ड किए और बिना grace window के secret बनाता है।
सुरक्षित Rotation प्रक्रिया
24-घंटे के grace window के कारण, संचालनों का कोई आवश्यक क्रम नहीं है — आपका receiver इस दौरान काम करता रहता है। अनुशंसित क्रम है:1
Secret को rotate करें
Dashboard से या API के माध्यम से rotate करें। Ayrshare तुरंत आपके पिछले और आपके नए secret दोनों से deliveries को sign करना शुरू कर देता है।
2
अपने receiver को अपडेट करें
24 घंटे के भीतर, नए secret को अपने webhook receiver पर डिप्लॉय करें ताकि यह नए मान के विरुद्ध सत्यापित करे।
3
Window को बंद होने दें
24 घंटे के बाद, Ayrshare स्वचालित रूप से previous secret को clear कर देता है और केवल नए secret से sign करता है। आपकी ओर से किसी और कार्रवाई की आवश्यकता नहीं है।
यदि आप एक grace window के अभी भी open रहते हुए फिर से rotate करते हैं, तो अभी-अभी
supersede किया गया secret नया previous secret बन जाता है और एक नया 24-घंटे का window
शुरू होता है। एक समय में केवल एक previous secret रखा जाता है।
Grace Window के दौरान Signatures का सत्यापन
एक grace window के बाहर, signed deliveries standard headers ले जाती हैं (देखें Webhook Security):X-Authorization-Timestamp : <Unix Timestamp In Seconds>
X-Authorization-Content-SHA256 : <current-sig>
X-Authorization-Content-SHA256-V2 : v1=<current-sig>
X-Authorization-Content-SHA256-V2 header दोनों signatures सूचीबद्ध करता है, current पहले, comma-separated:
X-Authorization-Timestamp : <Unix Timestamp In Seconds>
X-Authorization-Content-SHA256 : <current-sig>
X-Authorization-Content-SHA256-V2 : v1=<current-sig>,v1=<previous-sig>
X-Authorization-Content-SHA256 अपरिवर्तित है: यह हमेशा एकल current-secret HMAC ले
जाता है, backward compatibility के लिए। Dual signatures केवल नए
X-Authorization-Content-SHA256-V2 header में दिखाई देते हैं।X-Authorization-Content-SHA256-V2 में प्रत्येक मान एक scheme tag के साथ prefixed है। v1= एक HMAC-SHA256 signature को दर्शाता है, जो ठीक X-Authorization-Content-SHA256 की तरह गणना की जाती है। -V2 header हमेशा तब मौजूद रहता है जब कोई delivery signed होती है — यह कम से कम v1=<current-sig> ले जाता है — इसलिए आप इसे एक stable receiver contract के रूप में उपयोग कर सकते हैं।
Rotation के दौरान (या बाहर) एक delivery को सत्यापित करने के लिए:
1
HMAC की गणना करें
अपने locally configured signing secret का उपयोग करके raw request body का HMAC-SHA256 गणना करें।
2
प्रत्येक सूचीबद्ध signature के विरुद्ध तुलना करें
X-Authorization-Content-SHA256-V2 पढ़ें, इसे commas पर विभाजित करें, प्रत्येक मान से v1= prefix हटाएँ, और यदि आपका गणना किया गया HMAC किसी भी सूचीबद्ध v1= signature से मेल खाता है तो delivery को authentic के रूप में स्वीकार करें।v1=<previous-sig> से मेल खाता है, जबकि नए secret पर अपडेट किया गया receiver v1=<current-sig> से मेल खाता है — window के दौरान दोनों सफल होते हैं।
Receiver सत्यापन उदाहरण
Node.js
import crypto from "crypto";
// secret is the signing secret currently configured on your receiver.
function isAuthenticWebhook(rawBody, headers, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody) // the raw, unparsed request body
.digest("hex");
const headerValue = headers["x-authorization-content-sha256-v2"] || "";
// Accept if ANY v1= signature in the header matches our computed HMAC.
return headerValue
.split(",")
.map((part) => part.trim())
.filter((part) => part.startsWith("v1="))
.map((part) => part.slice("v1=".length))
.some((sig) => {
const sigBuf = Buffer.from(sig);
const expectedBuf = Buffer.from(expected);
// timingSafeEqual throws on length mismatch — treat as not authentic.
return (
sigBuf.length === expectedBuf.length &&
crypto.timingSafeEqual(sigBuf, expectedBuf)
);
});
}
हमेशा HMAC की गणना raw request body bytes पर करें, ठीक वैसे ही जैसे प्राप्त हुए
— न कि किसी re-serialized JSON object पर। Re-serialization whitespace या key order
को बदल सकता है और सत्यापन को तोड़ सकता है। Timing attacks से बचने के लिए एक
constant-time तुलना (जैसे
crypto.timingSafeEqual) का उपयोग करें।