Neidio i’r prif gynnwys

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.

gwybodaeth

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.

Amgen websocket amser-real

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

cyngor

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

gwybodaeth

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.

Ciplun o Adran Webhooks

perygl

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.

gwybodaeth

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.

data dogfen yn ngrok

Mae ceisiadau yn cyrraedd fel cais POST sy’n cynnwys JSON. Sylwer, gall cynnwys ‘data’ ehangu i gynnwys mwy o feysydd dros amser.

cyngor

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’:

objectevent
documentcreated
documentrejected
documentfinalPdfCreated
recipientcompleted
recipientrejected
recipientemailOpened
recipientvisiting
recipientbounced
recipientautoReminderEmail
recipientemailNotification

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.

rhybudd

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’:

data derbynnydd yn ngrok

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)"
gwybodaeth

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"
]
}