Neidio i’r prif gynnwys

Webhooks ar Legalesign

Beth yw webhooks​

Mae webhooks yn eich URLs chi lle bydd Legalesign yn anfon diweddariadau statws amser-real. Gallwch greu eich URLs eich hun neu gall systemau awtomeiddio (fel MS Power Automate) eu cynhyrchu i ddechrau llif gwaith.

Er enghraifft, yn y demos hyn rydym yn creu URL gyda Microsoft Power Automate. Rydym yn ychwanegu’r URL hwnnw fel y webhook yn Legalesign pan fydd dogfennau yn cael eu llofnodi. Caiff llif Power Automate ei daro pan fydd dogfen yn cael ei llofnodi ac yn awtomatig yn cadw’r PDFs newydd llofnodedig hynny i Sharepoint. Dysgwch fwy am MS Power Automate.

gwybodaeth

Nodyn pwysig - rhaid i chi fod â hawliau Gweinidog tîm i dderbyn digwyddiadau tîm wedi’u hanfon i’ch webhook.

Pam mae angen webhooks arnoch chi​

Mae webhooks yn eich galluogi i gynnal system sy’n cael ei gyrru gan ddigwyddiadau. Bydd webhooks yn eich diweddaru ar bob digwyddiad o fewn eich grwpiau. Efallai y byddwch yn eu defnyddio i greu’ch ddesg wedi’i chynnal byw eich hun a/neu eu defnyddio i gydamseru gydag eich sylfaen ddata eich hun.

Fel y crybwyllwyd uchod, mae webhooks a gynhyrchir gan systemau awtomeiddio fel Power Automate yn eich galluogi i ddechrau gweithdrefnau storio, e-byst, cadw cofnodion, ac ati, sy’n cynnig popeth sydd ei angen arnoch chi ar gyfer awtomeiddio proses, ynghyd â’r API.

Amgen weinydd gwe websocket amser-real

Mae tanysgrifiad websocket amser-real hefyd ar gael. Gall hyn fod yn opsiwn gwell pan ydych eisiau diweddariadau byw ar ochr y cleient heb ddatgelu pwynt terfyn webhook. Mae’r websocket yn datgelu set ehangach o ddigwyddiadau nag webhooks.

Gweler: Dechrau Cyflym Websocket Amser-Real

cyngor

Ie, mae webhooks yn ymddangos yn gymhleth, ond maent yn werth eu gwaith ac yn wych ar gyfer eich integreiddiad. Darllenwch ymlaen.

Mathau o webhook​

  • Digwyddiadau amser-real
  • Pob digwyddiad bob 6 munud (treftadaeth)
  • Ar ôl [ddigwyddiad] (treftadaeth)

Ar gyfer webhooks treftadaeth gweler: webhooks treftadaeth

gwybodaeth

Defnyddir webhooks fwyafrifol i lawrlwytho PDF wedi’i lofnodi. Pan fyddwch yn creu’r webhook, defnyddiwch hidlydd digwyddiad 'Final PDF created'. Yn eich cod, mae’r request.body sy’n dod i mewn yn JSON, ei bparsio a thynnu documentId = ['data']['uuid']. Yna rhyddhewch y cais 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 dashboard API a chlicio i’r adran Webhooks. Mae gan y ffurflen reolaethau syml i ychwanegu neu dynnu webhooks. Gallwch hefyd yn ddewisol ynysu digwyddiadau webhook i dimau penodol a/neu ddigwyddiadau.

Sgrinlun o Adran Webhooks

perygl

Mae eich webhooks yn derbyn digwyddiadau o bob cyfrif lle ydych chi’n gweinyddwr, datblygol a chynhyrchiol. Defnyddiwch y hidlydd grŵp i greu gwahanol webhooks ar gyfer eich grwpiau amrywiol.

Ychwanegu neu dynnu webhook gan ddefnyddio’r REST API​

Gweler yr adran 'webhook' ar waelod y llywio chwith yn ddogfennaeth API: REST API webhooks

Ychwanegu neu dynnu webhook gan ddefnyddio GraphQL​

Newydd! Os ydych yn defnyddio dilysu SRP a rhyngwyneb GraphQL, mae gennych bŵer CRUD llawn. Edrychwch ar Archwiliwr Legalesign GraphiQL. Gellir rhestru webhooks fel nodwedd o'r math Defnyddiwr, ac mae mudiadau i createWebhook, updateWebhook a deleteWebhook.

Beth sydd mewn webhook?​

Y ffordd gyflymaf i archwilio’ch data yw ychwanegu webhook, anfon/lofnodi/gwrthod rhai dogfennau prawf yn yr ap gwe, ac yna gweld logiau webhooks yn y Dashboard API Legalesign.

Os oes angen URL webhook dros dro arnoch i brofi yna edrychwch ar ngrok.

Sut i ddefnyddio ngrok yn gyflym: unwaith i chi lawrlwytho ngrok, lansiwch hi yn y termynell gyda ./ngrok http 80 a bydd yn rhoi cyfeiriad https i chi. Rhowch hwnnw fel eich webhook. Nawr agorwch http://127.0.0.1:4040. Dyna ni, byddwch yn dechrau gweld y webhooks a’u data. Ewch ati i anfon a llofnodi dogfennau prawf. Nodyn: Gall Ngrok ddychwelyd gwall 5XX, felly gallwch ddisgwyl gweld sawl ymgais ac negeseuon gwall gan fod y system yn ystyried statws 5XX fel ymgais aflwyddiannus.

gwybodaeth

Sicrhewch fod eich cod sy’n derbyn y webhook yn dychwelyd ymateb llwyddiannus 2XX. Os oes gennych sawl eithriad posibl yn eich cod, dychwelwch god gwall 5XX gwahanol. Bydd y logiau webhook yn y dashboard API yn dweud wrthych pa eithriad a sbardunodd.

Fformat webhook amser-real​

Gall y data fod mewn un o ddwy gyllell gynllun, naill ai cynllun 'document' neu 'recipient'. Archwiliwch y nodwedd 'object' i benderfynu pa gyllell gynllun yr ydych yn ei ddelio gyda hi.

Mae gan y ddwy gyllell gynllun hefyd nodwedd 'event'. Gallwch hidlo yn ôl 'object' a ymhelaethu ar yr 'event' wrth greu’r webhook.

Mae tabl o bob gwrthrych a digwyddiad posibl isod. Mae’r ddelwedd hon yn dangos gwrthrych dogfen (ar gyfer digwyddiad 'created'). Mae’r cynlluniau JSON llawn yn ychwanegol ar waelod y darn hwn.

data dogfen yn ngrok

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

cyngor

Defnyddiwch nodweddion 'tag'. Gallwch osod hyd at 3 tag pan fyddwch yn creu dogfen. Trwy ddefnyddio tags efallai na fydd angen i chi arbed IDau Legalesign. Gallwch hefyd ddefnyddio tag i gadw cyfrinach er mwyn gwirio’r cais sy’n dod i mewn (diolch i Themis am y syniad hwn).

Tabl o gyfuniadau posibl ar gyfer 'object' a 'event':

gwrthrychdigwyddiad
documentcreated
documentrejected
documentfinalPdfCreated
recipientcompleted
recipientrejected
recipientemailOpened
recipientvisiting
recipientbounced
recipientautoReminderEmail
recipientemailNotification

Mae’r rhan fwyaf o ddigwyddiadau yn digwydd unwaith yn unig. Y eithriadau yw visiting, bounced, emailNotification a autoReminderEmail, gallant ddigwydd sawl gwaith.

rhybudd

Peidiwch ag anghofio diffodd diogelwch 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 a emailBounceMessage yn 'data'. Bydd 'emailBounceMessage' yn nodi math y bounced fel a ganlyn:

  • Bounce caled: "Message hard bounced"
  • Bounce meddal: "Email soft bounced (either out of office or a timeout)"
  • Wedi oedi: "Message delayed (check email domain exists)"
gwybodaeth

Gall y cynllun ychwanegu nodweddion newydd unrhyw bryd.

Dadansoddi webhooks yn y dashboard API​

Mae pob webhook yn cael ei logio a gallwch archwilio eu cynnwys a’r cod statws http yn eich dashboard API. I ddysgu mwy gweler y Tiwtorial Dashboard

Dechrau llaw webhook​

Dechreuwch webhook yn llaw gan ddefnyddio’r ffurflen ar waelod tudalen Webhooks yn eich Porth Datblygwr.

Gwnewch yn siŵr eich bod yn defnyddio ID derbynnydd neu ddogfen go iawn, yn dibynnu ar y digwyddiad.

Codau statws​

Cliciwch y dolenni hyn i weld y tabl cyfeirnod ar gyfer statws dogfen a statws derbynnydd.

Cadarnhau webhook​

Mae’r webhook yn llofnodi’r pecyn data gyda allwedd breifat. Gallwch ei gadarnhau gyda’r allwedd gyhoeddus - lawrlwythwch allwedd gyhoeddus.

  • Lleoliad y llofnod yn y pennawd yw X-Signed-SHA256.
  • Y data sy’n cael ei lofnodi yw’r cyfan request.body (fel string).

Mae’r 'llofnod' wedi’i godio base64. Dyma god cadarnhau sampl 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');

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));

Mwy o webhook?​

Os oes angen mwy o webhooks arnoch ar gyfer digwyddiadau gwahanol, neu fwy o ddata ynddynt, cysylltwch â ni a chael eich cais yn y piblin datblygu.

Cyfeirnod cynllun​

Mae dau gyllell cynllun posibl, un ar gyfer gwrthrych 'document' ac un ar gyfer gwrthrych 'recipient'. Mae gan y ddwy gyllell gynllun allweddi lefel uchaf 'object' a 'event'. Archwiliwch y nodwedd 'object' i benderfynu pa gynllun rydych yn ei ddilyn. Neu defnyddiwch hidlydd webhook i ddychwelyd dim ond gwrthrychau dogfennau neu dim ond gwrthrychau derbynnwyr.

Sylwch fod cynllun yn gallu cael nodweddion newydd yn cael eu hychwanegu unrhyw bryd (ond ni fydd yn lleihau).

1. Cynllun 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. Cynllun 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"
    ]
  }
Diwygiedig ddiwethaf ar

Export This Article

Save a copy of this page as PDF or plain text.