Webhooks ar Legalesign
Cad iad na webhooks
Is iad na webhooks do URLs ina sheolfar nuashonruithe stádais i bhfíor-am ó Legalesign chugat. Is féidir leat do chuid féin URLs a chruthú nó gur féidir le córais uathoibrithe (mar MS Power Automate) iad a ghiniúint chun sreabhadh oibre a thosú.
Mar shampla, sa dtaispeántas seo cruthaímid URL le Microsoft Power Automate. Cuirimid an URL sin leis mar an webhook i Legalesign nuair a shíntear doiciméid. Déantar sreabhadh Power Automate a spreagadh nuair a shíntear doiciméad agus sábhálann sé go huathoibríoch na PDFanna sin atá sínithe nua chuig Sharepoint. Foghlaim níos mó faoi MS Power Automate.
Nóta tábhachtach - caithfidh tú ceadanna Riaracháin foirne a bheith agat chun imeachtaí foirne a fháil ar do webhook.
Cén fáth go bhfuil gá le webhooks
Cuireann webhooks ar do chumas córas a oibríonn ar imeachtaí a chothabháil. Nuashonróidh webhooks thú ar gach imeacht laistigh de do ghrúpaí. B’fhéidir gur úsáidfidh tú iad chun do dhoirseán beo féin a chruthú agus/nó chun comhréiteach a dhéanamh le d’bhunachar sonraí féin.
Mar a luadh thuas, cuireann webhooks ginte ó chórais uathoibrithe cosúil le Power Automate ar do chumas nósanna stórála, ríomhphoist, coimeádta taifead, srl a thosú, a chuidíonn, i gcomhthráth leis an API, le gach rud atá uait le haghaidh uathoibriú próisis.
Tá soláthar síntiús websocket fíor-ama ar fáil freisin. Is féidir go mbeidh sé níos oiriúnaí nuair ba mhaith leat nuashonruithe beo ar thaobh an chliaint gan deireadhphointe webhook a nochtadh. Nochtann an websocket tacar níos leithne d’imeachtaí ná webhooks.
Sea, braitheann webhooks mar chruachás, ach tá siad an-úsáideach agus go hiontach do do chomhtháthú. Léigh ar aghaidh.
Cineálacha webhook
- Imeachtaí fíor-ama
- Gach imeacht gach 6 nóiméad (seanaoiseach)
- Ag [imeacht] (seanaoiseach)
Maidir le webhooks seandaoiseacha féach: webhooks seandaoiseacha
Is é an úsáid is coitianta le haghaidh webhooks ná PDF sínithe a íoslódáil. Nuair a chruthaíonn tú an webhook cuir scagaire imeachta 'Cruthaíodh an PDF Deiridh' i bhfeidhm. I do chód, tá an request.body isteach i bhformáid JSON, déan é a pharsáil agus bain amach documentId = ['data']['uuid']. Anois déan an fiosrúchán API chun an PDF a íoslódáil - GET https://eu-api.legalesign.com/api/v1/pdf/${documentId}/.
Conas webhook a chur leis nó a bhaint
Webhook a chur leis nó a bhaint ag úsáid an aip gréasáin
Tabhair cuairt ar Painéal API agus cliceáil ar an rannán Webhooks. Tá rialuithe simplí ag an bhfoirm chun webhooks a chur leis nó a bhaint. Is féidir leat imeachtaí webhook a scagadh go roghnach do fhoirne áirithe agus/nó imeachtaí.
Faigheann do webhooks imeachtaí ó gach cuntas ina bhfuil tú mar riarachán, idir fhorbróir agus táirgeadh. Úsáid an scagaire grúpaí chun webhooks éagsúla a chruthú do do ghrúpaí éagsúla.
Webhook a chur leis nó a bhaint ag úsáid an REST API
Féach an rannán 'webhook' ag bun an nascleanúna clé laistigh den doiciméad API: REST API webhooks
Webhook a chur leis nó a bhaint ag úsáid GraphQL
Nua! Má tá tú ag úsáid fíordheimhnithe SRP agus an comhéadan GraphQL, tá cumhachtaí feidearacha lán agat. Féach ar Legalesign GraphiQL Explorer. Is féidir webhooks a liostáil mar airíonna den chineál User, agus tá athruithe ann chun createWebhook, updateWebhook agus deleteWebhook a dhéanamh.
Cad atá i webhook?
Is é an bealach is tapúla le do shonraí a iniúchadh ná webhook a chur leis, roinnt doiciméad tástála a sheoladh/shíniú/inniú a dhiúltú san aip gréasáin, agus ansin logaí na webhooks a fheiceáil i Painéal API Legalesign.
Má tá URL webhook sealadach uait le haghaidh tástála ansin féach ar ngrok.
Treoir gasta faoi ngrok: nuair a íoslódálann tú ngrok, cuir isteach san teirminéal é leis an ordú ./ngrok http 80 agus tabharfaidh sé seoladh https duit. Cuir isteach é sin mar do webhook. Anois oscail http://127.0.0.1:4040. Sin é, tosóidh tú ag feiceáil na webhooks go léir agus a sonraí. Tosaigh ag seoladh agus ag síniú doiciméid tástála. Nóta: D’fhéadfadh ngrok earráid 5XX a thabhairt ar ais, mar sin is féidir leat a bheith ag súil le roinnt iarrachtaí agus teachtaireachtaí earráide ós rud é go mbrisfidh an córas stádas 5XX mar iarracht theipthe.
Déan cinnte go dtugann do chód ag fáil webhooks freagra rathanna 2XX ar ais. Má tá roinnt eisceachtaí féideartha i do chóid tabhair freagra cód stádais 5XX éagsúil ar ais. Déanfaidh logaí an webhook i Painéal API ansin a insint duit cén eisceacht a spreagadh.
Foirformáid webhook fíor-ama
Is féidir le foirformáid sonraí a bheith ar cheann de dhá scéim, scéim 'doiciméad' nó scéim 'faighteora'. Scrúdaigh an tréith 'object' chun a fháil amach cén scéim atá i gceist agat.
Tá tréith 'imeachta' ag an dá scéim freisin. Is féidir leat scagadh de réir object agus roghnach de réir imeachta nuair a chruthaíonn tú an webhook.
Tá tábla de na rudaí agus imeachtaí is féidir thíos. Léiríonn an íomhá seo réad doiciméid (do imeacht 'cruthaithe'). Tá na scéimeanna JSON iomlána ag bun an ailt seo.
Tagann na hiarratais mar iarratas POST a bhfuil JSON iontu. Tabhair faoi deara, d’fhéadfadh go leathnófaí ábhar 'data' le haon réimsí breise le himeacht ama.
Úsáid tréithe 'tag'. Is féidir suas le 3 tag a shocrú agat nuair a chruthaíonn tú doiciméad. Trí thaganna a úsáid, b’fhéidir nach mbeidh ort IDanna Legalesign a shábháil. Is féidir leat tag a úsáid freisin chun rúnda a shábháil chun an iarraidh a fhaigheann tú a fhíorú (go raibh maith agat Themis as an moladh sin).
Tábla foirmeacha féideartha le haghaidh '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 |
Ní tharlaíonn na himeachtaí is mó ach uair amháin amháin. Na heisceachtaí ná visiting, bounced, emailNotification agus autoReminderEmail, d’fhéadfadh siad tarlú go minic.
Ná déan dearmad cosaint CSRF a mhúchadh don amharc atá ag fáil na n-iarratas POST seo.
Seo sampla d’iris 'recipient', le himeacht 'bounced':
Tabhair faoi deara emailBounce agus emailBounceMessage i 'data'. Léireoidh 'emailBounceMessage' cineál an bounce mar seo a leanas:
- Bounce crua: "Message hard bounced"
- Bounce bog: "Email soft bounced (either out of office or a timeout)"
- Moillithe: "Message delayed (check email domain exists)"
D’fhéadfadh tréithe nua a chur leis an scéim am ar bith.
Déan dífhabhtú ar webhooks sa phainéal API
Tá gach webhook logáilte agus is féidir leat a n-ábhar agus cód stádais http a scrúdú i do phainéal API. Chun tuilleadh eolas a fháil féach ar an Ceacht ar an mPainéal
Spreagadh láimhe webhook
Spreag webhook de láimh ag úsáid an fhoirme ag bun leathanach Webhooks i do [Tollán Forbróra] (https://developer.legalesign.com).
Déan cinnte go n-úsáideann tú faighteoir fíor nó ID doiciméid, ag brath ar an imeacht.
Cóid stádais
Cliceáil ar na naisc seo chun an tábla tagartha a fheiceáil do stádas doiciméad agus stádas faighteora.
Fiúntas webhook
Síníonn an webhook an pacáiste sonraí leis an eochair phríobháideach. Is féidir leat é a fhíorú leis an eochair phoiblí - íoslódáil eochair phoiblí.
- Tá suíomh an téacs sínithe sa cheannlíne X-Signed-SHA256.
- Is í an fhaisnéis a shínítear ná an request.body iomlán (mar théacs).
Tá an ‘síniú’ códaithe mar base64. Seo cód samplach fíoraithe i 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');
Roghnach, tá fíorú bunaithe ar HMAC ar fáil freisin. Maidir leis an HMAC, roinntear eochair rúnda do do webhooks leat. Beidh an luach sínithe ina cheannlíne X-HMAC-SHA256.
Tá go leor acmhainní ar líne a léiríonn conas luach HMAC a fhíorú. Sampla fíoraithe i python ná:
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
Nó sampla cód Apex Salesforce chun HMAC a fhíorú ná:
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));
Níos mó webhook?
Má theastaíonn níos mó webhooks uait do imeachtaí éagsúla, nó níos mó sonraí iontu, déan teagmháil linn agus cuir d’iarratas isteach sa phíblíne forbartha.
Tagairt scéime
Tá dhá scéim fhéideartha, ceann do réad 'document' agus ceann do réad 'recipient'. Tá eochracha innéacs barrleibhéil 'object' agus 'event' ag an dá scéim. Scrúdaigh an tréith 'object' chun a fháil amach cén scéim atá i gceist agat. Nó úsáid scagairí webhook chun ach doiciméid nó ach faighteoirí a thabhairt ar ais.
Tabhair faoi deara go bhféadfadh tréithe nua a bheith curtha leis an scéim am ar bith (ach ní laghdófar iad).
1. Scéim JSON don réad '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. Scéim JSON don réad '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"
]
}