Webhooks air Legalesign

Dè na tha webhooks ann

'S iad na webhooks na URLs agad far am bi Legalesign a’ cur fiosan inbhe ann an àm fìor. Faodaidh tu do URLs fhèin a chruthachadh no faodaidh siostaman fèin-ghluasaid (mar MS Power Automate) an gineadh gus obrachadh air socradh a thòiseachadh.

Mar eisimpleir, anns an deamhain seo cruthaich sinn URL le Microsoft Power Automate. Bidh sinn a' cur an URL sin mar webhook ann an Legalesign airson nuair a thèid sgrìobhainnean a shoidhnigeadh. Bidh an sruth Power Automate air a bhrosnachadh nuair a thèid sgrìobhainn a shoidhnigeadh agus gu fèin-ghluasadach a' sàbhaladh na PDFan ùra soidhnichte sin gu Sharepoint. Ionnsachaibh barrachd mu MS Power Automate.

fiosrachadh

Nota cudromach - feumaidh tu ceadan Admin sgioba fhaighinn gus tachartasan sgioba a chuir gu do webhook.

Carson a dh'fheumas tu webhooks

Bidh webhooks gad chuideachadh le bhith a’ cumail siostam air a stiùireadh le tachartasan. Cuiridh webhooks fiosrachadh thugad mu na tachartasan a’ tachairt taobh a-staigh do bhuidhnean. Dh’fhaodadh tu an cleachdadh gus do bhùird-beò beò fhèin a chruthachadh agus/no an cleachdadh gus sioncronadh a dhèanamh leis an stòr-dàta agad fhèin.

Mar a chaidh ainmeachadh gu h-àrd, bidh webhooks gineadh bho shiostaman fèin-ghluasaid mar Power Automate a’ cur comas dhut pròiseasan stòraidh, puist-d, cumail clàran, msaa a thòiseachadh, a’ toirt suim còmhla ris an API, a’ toirt seachad a h-uile dad a dh’fheumas tu airson fèin-ghluasad phròiseasan.

Eileamaid websocket ann an àm fìor

Tha lìonra ballrachd websocket ann an àm fìor rim faighinn cuideachd. Faodaidh seo a bhith nas fhallaine nuair a bhios tu ag iarraidh ùrachaidhean beò taobh an neach-cleachdaidh gun a bhith a’ nochdadh deireadh-lìn webhook. Bidh an websocket a’ nochdadh raon nas fharsainge de tachartasan na webhooks.

Faic: Real-Time Websocket Quickstart

comhairle

Tha webhooks coltach ri obair chruaidh uaireannan, ach tha iad glè fheumail agus math airson do cheangal. Leugh tuilleadh.

Seòrsaichean webhook

• Tachartasan ann an àm fìor
• A h-uile tachartas gach 6 mionaid (seann dòigh)
• Air [tachartas] (seann dòigh)

Airson sean-webhooks faic: legacy webhooks

fiosrachadh

Bidh webhooks gu tric air an cleachdadh gus PDF soidhnichte a luchdachadh sìos. Nuair a chruthaicheas tu am webhook cuir an sìoltachan tachartas 'Final PDF created'. Annta do chòd, 's e JSON a bhios ann an an iarrtas a thig a-steach request.body, bris e agus tarraing a-mach documentId = ['data']['uuid']. An uairsin cuir an neach-iarrtais API a-mach gus am PDF a luchdachadh sìos - GET https://eu-api.legalesign.com/api/v1/pdf/${documentId}/.

Mar a chuireas tu webhook ris no a bheir às e

Cuir ris no cuir às do webhook a’ cleachdadh na h-aplacaid lìn

Rachaibh gu API dashboard agus cliog air an roinn Webhooks. Tha foirm le smachdan sìmplidh airson webhooks a chur ris no a thoirt air falbh. Faodaidh tu roghainneil tachartasan webhook a chuingealachadh ri sgiobaichean sònraichte agus/no tachartasan.

cunnart

Bidh do webhooks a’ faighinn tachartasan bho a h-uile cunntas far a bheil thu nad rianaire, agus thar an dà chuid leasachadh agus toradh. Cleachd an sìoltachan buidhne gus webhooks eadar-dhealaichte a chruthachadh airson do bhuidhnean eadar-dhealaichte.

Cuir ris no cuir às do webhook a’ cleachdadh an REST API

Faic an roinn ‘webhook’ aig bonn an nanachaidh chlì taobh a-staigh an leabhrainn API: REST API webhooks

Cuir ris no cuir às do webhook a’ cleachdadh GraphQL

Ùr! Ma tha thu a’ cleachdadh dearbhadh SRP agus an eadar-aghaidh GraphQL, tha cumhachdan CRUD agad gu tur. Thoir sùil air Legalesign GraphiQL Explorer. Faodar webhooks a liostadh mar thogalach den t-seòrsa User, agus tha atharrachaidhean ann airson createWebhook, updateWebhook agus deleteWebhook.

Dè tha ann an webhook?

Is e an dòigh as luaithe air do dhàta fhaicinn airson webhook a chur ris, beagan sgrìobhainnean deuchainn a chuir/signadh/diùltadh anns an aplacaid lìn, agus an uairsin coimhead air logaichean nan webhooks anns an Legalesign API Dashboard.

Ma tha URL webhook sealach a dhìth ort airson deuchainn, feuch ngrok.

Stiùireadh luath air ngrok: aon uair ‘s gu bheil thu a’ luchdachadh sìos ngrok, cuir e an gnìomh san inneal-crìochnachaidh le ./ngrok http 80 agus bheir e seòladh https dhut. Cuir a-steach an sin mar do webhook. Fosgail http://127.0.0.1:4040. Sin e, tòisichidh tu a’ faicinn a h-uile webhook agus na dàta aca. Tòisich a’ cur a-steach agus a’ soidhnigeadh sgrìobhainnean deuchainn. Nota: Dh’fhaodadh Ngrok mearachd 5XX a thoirt air ais, mar sin bi dùil ri iomadh oidhirp agus teachdaireachdan mearachd oir bheir an siostam an inbhe 5XX mar oidhirp fàilligte.

fiosrachadh

Dèan cinnteach gu bheil còd an webhook agad a’ toirt freagairt soirbheachaidh 2XX air ais. Ma tha grunn eisgeachdan rim faighinn anns a’ chòd agad, thoir freagairtean inbhe 5XX eadar-mheasgte. Innsidh logaichean nan webhook anns an API dashboard dhut an uairsin dè an eisgeachd a chaidh a ghluasad.

Cruth webhook ann an àm fìor

Faodaidh dà chruth dàta a bhith ann, no 'document' no 'recipient'. Sgrùdadh air a’ phrìomh chomas ‘object’ gus fios a bhith agad dè an cruth ris a bheil thu a’ dèiligeadh.

Tha an dà chruth cuideachd a’ toirt a-steach prìomh chomas ‘event’. Faodaidh tu sìoladh a dhèanamh a rèir ‘object’ agus roghainneil cuideachd ‘event’ nuair a chruthaicheas tu an webhook.

Tha clàr làn de gach nì agus tachartas aig a’ bhonn. Tha an ìomhaigh seo a’ sealltainn nì sgrìobhainn (tachartas ‘created’). Tha na cruthan JSON slàn air an cur ri bonn an artaigil seo.

Thig iarrtasan mar iarrtas POST a’ toirt a-steach JSON. Nota gu bheil feallsanachd ‘data’ a' leudachadh thar ùine gus barrachd raointean a thoirt a-steach.

comhairle

Cleachd prìomh chomain 'tag'. Faodaidh tu suas ri 3 tagaichean a shuidheachadh nuair a chruthaicheas tu sgrìobhainn. Le bhith a’ cleachdadh tagaichean dh’fhaodadh nach fheum thu na h-AIMEAN Legalesign a shàbhaladh. Faodaidh tu cuideachd taga a chleachdadh gus facal-faire a shàbhaladh gus dearbhadh a dhèanamh air an iarrtas a tha a’ tighinn a-steach (tapadh leat Themis airson an comhairle sin).

Clàr de na comasan '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

Chan tachair a’ mhòr-chuid de na tachartasan ach aon uair. Tha na h-eisgeachdan 'visiting', 'bounced', 'emailNotification' agus 'autoReminderEmail' a’ tachairt iomadh uair.

rabhadh

Na dìochuimhnich toirt dheth dìon CSRF airson am frèam faicsinneach agad a bhios a’ gabhail na POSTan a tha a’ tighinn a-steach seo.

Seo eisimpleir de 'recipient' object, leis an tachartas ‘bounced’:

Thoir an aire gu bheil emailBounce agus emailBounceMessage ann an 'data'. Seallaidh 'emailBounceMessage' an seòrsa bounce mar seo:

• Bounce cruaidh: "Message hard bounced"
• Bounce bog: "Email soft bounced (either out of office or a timeout)"
• Air a leudachadh: "Message delayed (check email domain exists)"

fiosrachadh

Faodaidh na prìomh chomain san schema a bhith air an cur ris uair sam bith.

Dearbhaich webhooks anns an API dashboard

Tha a h-uile webhook air a chlàradh agus faodaidh tu an susbaint agus còd inbhe http fhaicinn anns an API dashboard agad. Gus tuilleadh ionnsachadh faic an Dashboard tutorial

Brosnaich webhook gu làimhe

Brosnaich webhook gu làimhe a’ cleachdadh an fhoirm aig bonn duilleag Webhooks anns an Developer Portal.

Cùm ris a bhith a’ cleachdadh ID fìor ath-thogalach no sgrìobhainn, a rèir na tachartas.

Còd inbhe

Cliog air na ceanglaichean seo gus clàr iomraidh a’ faicinn airson inbhe sgrìobhainn agus inbhe ath-thogalach.

Dèan dearbhadh air webhook

Bidh am webhook a’ soidhnigeadh am pacaid dàta leis a’ phrìomh iuchair phrìobhaideach. Faodaidh tu dearbhadh a dhèanamh leis a’ phrìomh iuchair phoblach - luchdaich sìos an iuchair phoblach.

• Tha suidheachadh an eòla bhratach anns an ceann X-Signed-SHA256.
• Bidh an dàta a thathar a’ soidhnigeadh gu bhith mar an t-iarrtas gu lèir request.body (mar sreang).

Tha an 'signature' air a chruthachadh ann am base64. Seo còd dearbhaidh eisimpleireil 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');

Gu roghainneil, tha dearbhadh stèidhichte air HMAC rim faighinn cuideachd. Airson HMAC, tha iuchair dìomhair airson do webhooks air a roinn riut. Thig an luach soidhnichte anns an ceann X-HMAC-SHA256.

Tha tòrr stòran air-loidhne a’ sealltainn mar a nì thu dearbhadh air luach HMAC. Bhiodh còd dearbhaidh eisimpleireil ann am python:

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

No còd eisimpleireach Salesforce Apex airson dearbhadh HMAC:

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 webhook?

Ma tha feum agad air barrachd webhooks airson tachartasan eadar-dhealaichte, no barrachd dàta ann anotha, cuir fios thugainn gus do cheist a chur air loidhne leasachaidh.

Iomradh air schema

Tha dà sheòrsa comasach, fear airson nì ‘document’ agus fear eile airson nì ‘recipient’. Tha prìomh chomasan àrd-ìre ‘object’ agus ‘event’ aig an dà chuid. Sgrùdadh air ‘object’ gus am schema a tha thu a’ dèiligeadh ris a lorg. No cleachd sìoltachan webhook gus dìreach nithean ‘document’ no ‘recipient’ a thoirt air ais.

Thoiribh fa-near gu faodaidh prìomh chomain ùra a bhith air an cur ris uair sam bith (ach cha tèid an lughdachadh).

1. JSON Schema airson nì ‘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. JSON schema airson nì ‘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"
    ]
  }