Webhooks ar Legalesign
Beth yw webhooks
Mae webhooks yn eich URLau lle bydd Legalesign yn anfon diweddariadau statws amser-real. Gallwch greu eich URLau eich hun neu gall systemau awtomeiddio (fel MS Power Automate) eu cynhyrchu i gychwyn llif gwaith.
Er enghraifft, yn y demo hon rydym yn creu URL gyda Microsoft Power Automate. Rydym yn ychwanegu’r URL hwnnw fel y webhook yn Legalesign pan fydd dogfennau’n cael eu llofnodi. Caiff llif Power Automate ei gychwyn pan fydd dogfen yn cael ei llofnodi ac mae’n achub y PDFs newydd llofnodwyd i Sharepoint yn awtomatig. Dysgwch fwy am MS Power Automate.
Nodyn pwysig – rhaid i chi gael hawliau Admin tîm i gael digwyddiadau’r tîm yn cael eu hanfon i’ch webhook.
Pam mae arnoch angen webhooks
Mae webhooks yn eich galluogi i gynnal system a yrrir gan ddigwyddiadau. Bydd webhooks yn eich diweddaru am bob digwyddiad o fewn eich grwpiau. Efallai yr hoffech eu defnyddio i greu eich dangosfwrdd byw eich hun ac/neu i'u defnyddio i gynllunio gyda’ch cronfa ddata eich hun.
Fel y crybwyllwyd uchod, mae webhooks a gynhyrchir gan systemau awtomeiddio fel Power Automate yn eich galluogi i gychwyn gweithdrefnau storio, e-byst, cadw cofnodion, ac ati, sydd, ynghyd â’r API, yn darparu popeth sydd ei angen arnoch ar gyfer awtomeiddio prosesau.
Mae tanysgrifiad websocket amser-real ar gael hefyd. Gall hyn fod yn opsiwn gwell pan fyddwch eisiau diweddariadau byw ar ochr y cleient heb ddatgelu pwynt terfyn webhook. Mae'r websocket yn datgelu set ehangach o ddigwyddiadau nag webhooks.
Gweler: Real-Time Websocket Quickstart
Ie, mae webhooks yn teimlo fel gwaith ychwanegol, ond maent yn werth chweil ac yn wych ar gyfer eich integreiddio. Darllenwch ymlaen.
Mathau o webhook
- Digwyddiadau amser-real
- Pob digwyddiad bob 6 munud (henaint)
- Ar [ddigwyddiad] (henaint)
Am webhooks hen ffasiwn gweler: webhooks hen ffasiwn
Defnyddir webhooks yn fwyaf cyffredin i lawrlwytho PDF wedi’i lofnodi. Pan fyddwch yn creu'r webhook, cymhwyswch y hidlydd digwyddiad 'Final PDF created'. Yn eich cod, mae’r cais sy’n dod i mewn yn request.body yn JSON, dadgodwch ef a thynnwch allan documentId = ['data']['uuid']. Nawr defnyddiwch y cwestiwn API i lawrlwytho'r PDF - GET https://eu-api.legalesign.com/api/v1/pdf/${documentId}/.
Sut i ychwanegu neu dynnu webhook
Ychwanegu neu dynnu webhook gan ddefnyddio’r ap gwe
Ewch i API dashboard a chliciwch i’r adran Webhooks. Mae gan y ffurflen reolaethau syml i ychwanegu neu dynnu webhooks. Gallwch ddewisol ynysu digwyddiadau webhook i dimoedd penodol ac/neu ddigwyddiadau penodol.

Mae eich webhooks yn derbyn digwyddiadau o bob cyfrif lle ydych chi'n gweinyddwr, datblygu a chynhyrchu. Defnyddiwch y hidlydd grŵp i greu webhooks gwahanol ar gyfer eich grwpiau amrywiol.
Ychwanegu neu dynnu webhook gan ddefnyddio’r REST API
Gweler yr adran ‘webhook’ ar waelod y llywio chwith o fewn y dogfennaeth API: REST API webhooks
Ychwanegu neu dynnu webhook gan ddefnyddio GraphQl
Newydd! Yn Legalesign GraphiQL Explorer, wedi mewngofnodi i’ch cyfrif Legalesign, mae gennych bŵer CRUD llawn dros webhooks. Gellir rhestru webhooks fel nodwedd o'r math User, a mae symudiadau i createWebhook, updateWebhook a deleteWebhook.
Beth sy’n y webhook?
Y ffordd gyflymaf i archwilio’ch data yw ychwanegu webhook, anfon/llofnodi/gwrthod rhai dogfennau prawf yn yr ap gwe, ac yna gwylio logiau webhooks yn y Dashboard API Legalesign.
Os oes arnoch angen URL webhook dros dro ar gyfer profi, edrychwch ar ngrok.
Sut i ddefnyddio ngrok yn gyflym: unwaith i chi lawrlwytho ngrok, cychwynwch ef yn y terminal gyda ./ngrok http 80 a bydd yn rhoi cyfeiriad https i chi. Rhowch hynny fel eich webhook. Nawr agorwch http://127.0.0.1:4040. Dyna'r cyfan, byddwch yn dechrau gweld pob webhook a’u data. Dechreuwch anfon a llofnodi dogfennau prawf. Nodyn: Gall ngrok ddychwelyd gwall 5XX, felly byddwch yn gweld sawl ymgais a negeseuon gwall gan y bydd y system yn ystyried y statws 5XX fel ymgais a fethodd.
Sicrhewch fod eich cod derbyn webhook yn dychwelyd ymateb llwyddiant 2XX. Os oes gennych sawl eithriad posib yn eich cod, dychwelyd gwahanol godau statws 5XX. Bydd logiau webhook yn y dashboard API yn dweud wrthych pa eithriad a gafodd ei sbarduno.
Fformat webhook amser-real
Gall fformat y data fod yn un o ddau schemas, naill ai schema ‘dogfen’ neu schema ‘derbynnydd’. Archwiliwch y nodwedd ‘object’ i benderfynu pa schema ydych yn ei ddelio ag ef.
Mae gan y ddau schema hefyd nodwedd ‘event’. Gallwch hidlo yn ôl yr object a dewisol yn ôl yr event pan fyddwch yn creu'r webhook.
Mae tabl o bob gwrthrych a digwyddiad posibl isod. Mae’r ddelwedd hon yn dangos gwrthrych dogfen (ar gyfer digwyddiad ‘creu’). Mae'r schemas JSON lawn wedi’u hychwanegu at waelod y gwasanaeth hwn.

Mae ceisiadau yn cyrraedd fel cais POST sy’n cynnwys JSON. Sylwer, gall cynnwys ‘data’ ehangu i gynnwys mwy o feysydd dros amser.
Defnyddiwch nodweddion ‘tag’. Gallwch osod hyd at 3 tag wrth greu dogfen. Trwy ddefnyddio tagiau efallai na fydd angen i chi gadw IDau Legalesign. Gallwch hefyd ddefnyddio tag i gadw cyfrinair er mwyn gwirio’r cais sy’n dod i mewn (diolch Themis am y cynnig hwnnw).
Tabl o gyfuniadau posibl ar gyfer ‘object’ a ‘event’:
| object | event |
|---|---|
| document | created |
| document | rejected |
| document | finalPdfCreated |
| recipient | completed |
| recipient | rejected |
| recipient | emailOpened |
| recipient | visiting |
| recipient | bounced |
| recipient | autoReminderEmail |
| recipient | emailNotification |
Mae’r rhan fwyaf o ddigwyddiadau yn digwydd unwaith yn unig. Y rhai eithriadol yw visiting, bounced, emailNotification a autoReminderEmail, a all ddigwydd sawl gwaith.
Peidiwch ag anghofio diffodd diogelu CSRF ar gyfer eich golwg sy’n derbyn y ceisiadau POST hyn.
Dyma enghraifft o wrthrych ‘recipient’, gyda digwyddiad ‘bounced’:

Sylwch ar emailBounce ac emailBounceMessage yn ‘data’. Bydd ‘emailBounceMessage’ yn dangos math y bounce fel a ganlyn:
- Bounce caled: "Message hard bounced"
- Bounce meddal: "Email soft bounced (either out of office or a timeout)"
- Oedi: "Message delayed (check email domain exists)"
Gall y schema gael nodweddion newydd yn cael eu hychwanegu unrhyw bryd.
Dadansoddi webhooks yn y dashboard API
Mae pob webhook yn cael ei logio a gallwch archwilio eu cynnwys a chôd statws http yn eich dashboard API. I ddysgu mwy gweler y Tiwtorial Dashboard
Ymgais llaw i gychwyn webhook
Cychwynwch webhook â llaw gan ddefnyddio'r ffurflen ar waelod tudalen Webhooks yn eich Developer Portal.
Sicrhewch eich bod yn defnyddio derbynnydd neu ID dogfen go iawn, yn dibynnu ar y digwyddiad.
Codau statws
Cliciwch y ddolenni hyn i weld y tabl cyfeirnod ar gyfer statws dogfen a statws derbynnydd.
Gwirio webhook
Mae'r webhook yn llofnodi'r pecyn data gyda allwedd breifat. Gallwch ei wirio gyda'r allwedd gyhoeddus - lawrlwytho allwedd gyhoeddus.
- Lleoliad y llofnod yn y pennawd X-Signed-SHA256.
- Y data sydd wedi’i lofnodi yw'r holl request.body (fel llinyn).
Mae’r ‘llofnod’ wedi’i godio mewn base64. Dyma god prawf mewn 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');
Yn ddewisol, mae gwirio HMAC ar gael hefyd. Ar gyfer HMAC, rhoddir allwedd gyfrinachol ar eich cyfer ar gyfer eich webhooks. Bydd y gwerth llofnodedig yn cyrraedd yn y pennawd X-HMAC-SHA256.
Mae llawer o adnoddau ar-lein yn dangos sut i wirio gwerth HMAC. Byddai cod prawf yn python yn:
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
Neu cod Salesforce Apex prawf i wirio HMAC yw:
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));
Mwy o webhook?
Os oes arnoch angen mwy o webhooks ar gyfer gwahanol ddigwyddiadau, neu fwy o ddata ynddynt, cysylltwch â ni a chael eich cais yn y llinell ddatblygu.
Cyfeirnod schema
Mae dau schema posibl, un ar gyfer gwrthrych 'document' ac un arall ar gyfer gwrthrych 'recipient'. Mae gan y ddau galluoedd pen uchel ‘object’ a ‘event’. Archwiliwch y nodwedd ‘object’ i benderfynu pa schema rydych chi’n delio ag ef. Neu defnyddiwch hidlydd webhook i ddychwelyd dim ond dogfennau neu dim ond gwrthrychau derbynnydd.
Noder y gall y schema gael nodweddion newydd yn cael eu hychwanegu ar unrhyw adeg (ond ni fydd yn lleihau).
1. Schema JSON ar gyfer gwrthrych '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 ar gyfer gwrthrych '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"
]
}