Webhooks air Legalesign
Dè th’ ann an webhooks
’S iad na h-URLan agaibh far an cuir Legalesign fiosrachadh ùrachaidh inbhe fìor-ùine. Faodaidh sibh ur URLan fhèin a chruthachadh no faodaidh siostaman fèin-ghluasaid (mar MS Power Automate) gan gineadh airson tòiseachadh air sruth-obrach.
Mar eisimpleir, anns an deam sa chruthaich sinn URL le Microsoft Power Automate. Chuireas sinn an URL sin mar an webhook ann an Legalesign airson nuair a bhios sgrìobhainnean air an soidhnigeadh. Tha sruth Power Automate air a thòiseachadh nuair a bhios sgrìobhainn air a shoidhnigeadh agus gu fèin-obrachail a’ sàbhaladh nam PDFan ùr-ghnàthach sin gu Sharepoint. Barrachd ionnsachadh mu MS Power Automate.
Note cudromach – feumaidh ceadan Rianadair a bhith agaibh airson an sgioba gus tachartasan a chur chun an webhook agaibh.
Carson a tha feum agad air webhooks
Bidh webhooks gad chuideachadh gus siostam stèidhichte air tachartasan a chumail suas. Bidh webhooks gad ùrachadh mu gach tachartas taobh a-staigh do bhuidhnean. Is dòcha gun cleachd thu iad airson do bhòrd-beò fhèin a chruthachadh agus/no airson sioncronachadh leis an stòr-dàta fhèin agad.
Mar a chaidh ainmeachadh gu h-àrd, leigidh webhooks air an gineadh le siostaman fèin-ghluasaid mar Power Automate dhut tòiseachadh air modhan-obrach stòraidh, puist-d, cumail clàran, msaa, a chuidicheas leis a’ API agus a bheir dhut a h-uile càil a dh’ fheumas tu airson fèin-ghiùlan pròiseasan.
Tha sruth fo-sgrìobhaidh websocket fìor-ùine ri fhaighinn cuideachd. ’S dòcha gu bheil seo a’ freagairt nas fheàrr nuair a tha ùidh agad ann an ùrachaidhean beò air taobh an luchd-ceannach gun a bhith a’ sealltainn àite-fàgail webhook. Tha an websocket a’ taisbeanadh raon nas fharsainge de thachartasan na webhooks.
Tha fios agam gu bheil webhooks coltach ris an obair chruaidh, ach tha iad gu math luachmhor agus math airson do cho-cheangal. Leugh air adhart.
Seòrsaichean webhook
- Tachartasan fìor-ùine
- A h-uile tachartas a h-uile 6 mionaidean (seann-dhaoine)
- Aon uair ‘s gu bheil [tachartas] (seann-dhaoine)
Airson seann webhooks faic: legacy webhooks
Bithear a’ cleachdadh webhooks as trice airson PDF air a shoidhnigeadh a luchdachadh sìos. Nuair a chruthaicheas tu an webhook, cuir an sìoltachan tachartas ‘Final PDF created’ an sàs. Anns a’ chòd agad, tha an t-iarrtas a tha a’ tighinn a-steach anns an request.body ann an cruth JSON, dèan sgoltagh air agus tarraing a-mach documentId = ['data']['uuid']. An uairsin cuir an rannsachadh API a-mach airson am PDF a luchdachadh sìos – GET https://eu-api.legalesign.com/api/v1/pdf/${documentId}/.
Mar a chuireas tu webhook ris no mar a bheir thu air falbh e
Cuir ris no cuir às do webhook a’ cleachdadh an app-lìn
Rach gu dashboard API agus briog an earrann Webhooks. Tha foirm leis an smachd sìmplidh airson webhooks a chur ris no a thoirt air falbh. Faodaidh tu tachartasan webhook a shìoladh gu sgiobaichean sònraichte agus/no tachartasan sònraichte.

Bidh na webhooks agad a’ faighinn tachartasan bho gach cunntas far a bheil thu nad rianadair, ann an leasachadh agus toradh. Cleachd an sìoltachan buidhne gus diofar webhooks a chruthachadh airson na buidhnean agad fhèin.
Cuir ris no cuir às do webhook a’ cleachdadh an API REST
Faic an roinn ‘webhook’ aig bonn na taobh chlì ann an sgrìobhainn API: REST API webhooks
Cuir ris no cuir às do webhook a’ cleachdadh GraphQL
Ùr! Anns an Legalesign GraphiQL Explorer, fo-chòmhla ri do chunntas Legalesign, tha cumhachan CRUD slàn agad air webhooks. Faodar webhooks a liostadh mar thogalach den t-seòrsa User, agus tha atharrachaidhean ri thoirt a-steach airson createWebhook, updateWebhook agus deleteWebhook.
Dè tha ann an webhook?
Is e an dòigh as luaithe air do dhàta fhaicinn a bhith a’ cur ris an webhook, a’ cur no a’ soidhnigeadh cuid de sgrìobhainnean deuchainn san aplacaid-lìn agus an uairsin a’ coimhead logaichean nan webhooks anns an Legalesign API Dashboard.
Ma dh’ fheumas tu URL webhook sealach airson deuchainn, feuch ngrok.
Mar a chleachdas tu ngrok: aon uair ’s gu bheil thu air ngrok a luchdachadh sìos, cuir air bhog e anns a’ chrìoch chrìochnachaidh leis ./ngrok http 80 agus bheir e seòladh https dhut. Cuir a-steach sin mar an webhook agad. An uairsin fosgail http://127.0.0.1:4040. Sin agad e, tòisichidh tu a’ faicinn na webhooks uile agus na dàta aca. Tòisich air sgrìobhainnean deuchainn a chur agus a shoidhnigeadh. Note: Dh’ fhaodadh Ngrok mearachd 5XX a shealltainn, mar sin ‘s dòcha gun chì thu iomadh oidhirp is teachdaireachdan mearachd leis gun toir an siostam beachd air an inbhe 5XX mar oidhirp fàillteach.
Dèan cinnteach gun toir am prògram webhooks a gheibh thu freagairt soirbheachail 2XX air ais. Ma tha grunn earrannan comasach anns a’ chòd agad thoir freagairt 5XX eadar-dhealaichte. Innseas logaichean an webhook anns an API dashboard dè an earrann a chaidh a thòiseachadh.
Cruth nan webhooks fìor-ùine
Faodar an dàta a thig a-steach a bhith ann an dà chuid cruth-dàta, no cruth ‘document’ no cruth ‘recipient’. Dèan sgrùdadh air an eileamaid ‘object’ gus faighinn a-mach dè an cruth a tha thu a’ dèiligeadh ris.
Tha eileamaid ‘event’ aig an dà chruth cuideachd. Faodaidh tu sìoladh a dhèanamh air an ‘object’ agus gu roghnach air an ‘event’ nuair a chruthaicheas tu an webhook.
Tha clàr beag le seallaidhean de na h-uile nithean is tachartasan co-fhillte gu h-ìosal. Tha an ceangal seo a’ sealltainn nithean sgrìobhainn (airson tachartas ‘cruthachadh’). Tha na clàran JSON làn air an cuir aig bonn an aiste seo.

Tha iarrtas a’ tighinn mar iarrtas POST a’ toirt a-steach JSON. Thoir fa-near, gum faod an susbaint ‘data’ leudachadh thar ùine gus barrachd raointean a chur ris.
Cleachd na h-eileamaidean ‘tag’. Faodaidh tu suas ri 3 bileagan a shuidheachadh nuair a chruthaicheas tu sgrìobhainn. Le bhith a’ cleachdadh bileagan, ’s dòcha nach fheum thu IDan Legalesign a shàbhaladh. Faodaidh tu cuideachd bileag a chleachdadh airson dìomhair a shàbhaladh gus dearbhadh a dhèanamh air an iarrtas a tha a’ tighinn a-steach (tapadh leat Themis airson an molaidh sin).
Clàr air na cothroman gu lèir airson ‘object’ agus ‘event’:
| object | event |
|---|---|
| document | created |
| document | rejected |
| document | finalPdfCreated |
| recipient | completed |
| recipient | rejected |
| recipient | emailOpened |
| recipient | visiting |
| recipient | bounced |
| recipient | autoReminderEmail |
| recipient | emailNotification |
Tha a’ mhòr-chuid de thachartasan a’ tachairt aon turas a-mhàin. Tha earrannan a bharrachd airson visiting, bounced, emailNotification agus autoReminderEmail, ’s dòcha gum tachair iad iomadh uair.
Na dìochuimhnich dìon CSRF a chuir dheth airson an sealladh a tha a’ faighinn na tagraidhean POST seo.
Seo eisimpleir de nithean ‘recipient’ le tachartas ‘bounced’:

Thoir fa-near emailBounce agus emailBounceMessage anns an ‘data’. Seallaidh ‘emailBounceMessage’ diofar sheòrsaichean buncaidh mar a leanas:
- Bun buntàta cruaidh: "Message hard bounced"
- Bun buntàta bog: "Email soft bounced (either out of office or a timeout)"
- Leudachail: "Message delayed (check email domain exists)"
Faodaidh am foirmean a bhith a’ faighinn prìomh eileamaidean cur ris uair sam bith.
Deuchainn nan webhooks anns an API Dashboard
Tha na h-uile webhooks air an clàradh agus faodaidh tu an susbaint agus còd inbhe HTTP aca fhaicinn anns an API dashboard agad. Gus barrachd ionnsachadh faic an Dashboard tutorial
Brosnachadh làimhe webhook
Brosnaich webhook le làimh a’ cleachdadh an fhoirm aig bonn na duilleige Webhooks anns an Developer Portal.
Dèan cinnteach gu bheil thu a’ cleachdadh ID fìor den neach-fhaighinn no sgrìobhainn, a rèir an tachartais.
Còdannan inbhe
Briog air na ceanglaichean seo gus an clàr iomraidh fhaicinn airson inbhe sgrìobhainn agus inbhe neach-fhaighinn.
Dearbhaich webhook
Tha an webhook a’ soidhnigeadh a’ phacaid dàta le iuchair phrìobhaideach. Faodaidh tu a dhearbhadh leis an iuchair phoblach - luchdaich sìos an iuchair phoblach.
- Tha suidheachadh an teacsa ainmichte anns a’ cheann-sgrìobha X-Signed-SHA256.
- Bidh an dàta air a shoidhnigeadh mar an t-soithichean iomlan request.body (mar sreang).
Tha an ‘signature’ air a chòdachadh ann am base64. Seo còd dearbhaidh eisimpleir ann an node.js:
const crypto = require('crypto');
const fs = require('fs');
const cert = fs.readFileSync('/location/of/downloadedCert.crt', 'utf8');
const c = new crypto.X509Certificate(cert);
const k = c.publicKey
let verifier = crypto.createVerify('SHA256');
let rawdata = 'sentdata' //JSON stringify data in request.body
let sha256signature = 'xxx' //value of 'X-Signed-Sha256' request header.
verifier.update(rawdata);
return verifier.verify(k, sha256signature, 'base64');
Optionally HMAC based verification is available too. For HMAC, a secret key for your webhooks is shared with you. The signed value will arrive in the header X-HMAC-SHA256.
There are lots of online resources that demonstrate how to verify an HMAC value. Sample verification in python would be:
import hmac, hashlib
sentdata = 'sentdata' # JSON stringify data in request.body
hmacvalue = 'xxx' # value of 'X-HMAC-Sha256' in request header.
v = hmac.new('your secret value'.encode(), 'sentdata'.encode(), hashlib.sha256)
isValid = v.hexdigest() == hmacvalue
Or sample Salesforce Apex code to verify a HMAC is:
String message = 'JSONstring'; //sent in request.body
String privatekey = 'privateKey'; //shared value you have been given
String hmacvalue = 'xxx'; //value of 'X-HMAC-Sha256' in request header.
Boolean verified = Crypto.verifyHMac('HmacSHA256', Blob.valueOf(message), Blob.valueOf(privatekey), EncodingUtil.convertFromHex(hmacvalue));
Barrachd webhooks?
Ma dh’ fheumas tu barrachd webhooks airson tachartasan eadar-dhealaichte, no barrachd dàta anns annta, cuir fios thugainn agus cuir do iarrtas dhan loidhne leasachaidh.
Iomradh air foirmlean
Tha dà schema comasach, aon airson an ‘document’ agus aon eile airson an ‘recipient’. Tha prìomh iuchraichean àrd-ìre ‘object’ agus ‘event’ aig an dà schema. Dèan sgrùdadh air an eileamaid ‘object’ gus faighinn a-mach dè am schema a tha thu a’ dèiligeadh ris. No cleachd sìoltachan webhook gus dìreach nithean sgrìobhainn no dìreach nithean luchd-fhaighinn a thoirt air ais.
Thoir fa-near gum faodadh e bhith gu bheil feum air eileamaidean ùra a chur ris an schema aig àm sam bith (ach cha lùghdaich iad).
1. Schema JSON airson an nithean ‘document’
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"default": "1.0.0"
},
"object": {
"type": "string",
"default": "document"
},
"created": {
"type": "integer",
"description": "unix timestamp"
},
"id": {
"type": "string",
"format": "uuid"
},
"event": {
"type": "string",
"pattern": "^(created|rejected|finalPdfCreated)$"
},
"data": {
"type": "object",
"properties": {
"tag1": {
"type": "string"
},
"recipients": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"order": {
"type": "integer"
},
"status": {
"type": "integer"
"pattern": "^(4|5|10|15|20|30|35|39|40|50|60)$"
},
"lastname": {
"type": "string"
},
"roleText": {
"type": "string",
"pattern": "^(signer|approver|witness)$"
},
"firstname": {
"type": "string"
},
"statusText": {
"type": "string",
"pattern": "^(unsent|scheduled|sent|email opened|visited|fields complete|fields complete excluding signature|witnessing required|completed|download final document|rejected|withdrawn)$"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"rejectReason": {
"type": "string"
}
},
"required": [
"uuid",
"email",
"order",
"status",
"lastname",
"roleText",
"firstname",
"statusText",
"resourceUri",
"rejectReason"
]
}
]
},
"groupResourceUri": {
"type": "string",
"format": "uri-reference"
},
"statusText": {
"type": "string",
"pattern": "^(available|fields complete|completed|removed|rejected|unknown)$"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"tag2": {
"type": "string"
},
"group": {
"type": "string"
},
"status": {
"type": "integer",
"pattern": "^(10|20|30|40|50)$"
}
},
"required": [
"tag1",
"recipients",
"groupResourceUri",
"statusText",
"name",
"tag",
"resourceUri",
"uuid",
"tag2",
"group",
"status"
]
}
},
"required": [
"version",
"object",
"data",
"created",
"id",
"event"
]
}
2. Schema JSON airson an nithean ‘recipient’
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"default": "1.0.0"
},
"object": {
"type": "string",
"default": "recipient"
},
"created": {
"type": "integer",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"event": {
"type": "string",
"pattern": "^(emailOpened|bounced|visiting|rejected|completed|autoReminderEmail|emailNotification)$"
},
"data": {
"type": "object",
"properties": {
"tag": {
"type": "string"
},
"tag1": {
"type": "string"
},
"tag2": {
"type": "string"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"group": {
"type": "string",
"format": "uuid"
},
"order": {
"type": "integer"
},
"status": {
"type": "integer",
"pattern": "^(4|5|10|15|20|30|35|39|40|50|60|70)$"
},
"document": {
"type": "string"
},
"documentName": {
"type": "string"
},
"lastname": {
"type": "string"
},
"roleText": {
"type": "string"
},
"firstname": {
"type": "string"
},
"statusText": {
"type": "string",
"pattern": "^(unsent|scheduled|sent|email opened|visited|fields complete|fields complete excluding signature|witnessing required|completed|download final document|rejected|withdrawn)$"
},
"emailBounce": {
"type": "integer"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"rejectReason": {
"type": "string"
},
"groupResourceUri": {
"type": "string",
"format": "uri-reference"
},
"emailBounceMessage": {
"type": "string"
},
"documentResourceUri": {
"type": "string",
"format": "uri-reference"
}
},
"required": [
"tag",
"tag1",
"tag2",
"uuid",
"email",
"group",
"order",
"status",
"document",
"documentName",
"lastname",
"roleText",
"firstname",
"statusText",
"emailBounce",
"resourceUri",
"rejectReason",
"groupResourceUri",
"emailBounceMessage",
"documentResourceUri"
]
}
},
"required": [
"version",
"object",
"data",
"created",
"id",
"event"
]
}