Webhooks στο Legalesign
Τι είναι τα webhooks
Τα webhooks είναι οι διευθύνσεις URL σας όπου το Legalesign θα στέλνει ενημερώσεις κατάστασης σε πραγματικό χρόνο. Μπορείτε να δημιουργήσετε τις δικές σας διευθύνσεις URL ή τα συστήματα αυτοματισμού (όπως το MS Power Automate) να τις δημιουργούν για να ξεκινήσουν μια ροή εργασίας.
Για παράδειγμα, σε αυτήν την επίδειξη δημιουργούμε μια διεύθυνση URL με το Microsoft Power Automate. Προσθέτουμε αυτή τη διεύθυνση URL ως webhook στο Legalesign για όταν υπογράφονται έγγραφα. Η ροή Power Automate ενεργοποιείται όταν υπογράφεται ένα έγγραφο και αποθηκεύει αυτόματα τα πρόσφατα υπογεγραμμένα PDF στο Sharepoint. Μάθετε περισσότερα για το MS Power Automate.
Σημαντική σημείωση - πρέπει να έχετε δικαιώματα Admin στην ομάδα για να λαμβάνετε γεγονότα ομάδας στο webhook σας.
Γιατί χρειάζεστε webhooks
Τα webhooks σας επιτρέπουν να διατηρήσετε ένα σύστημα βασισμένο σε συμβάντα. Τα webhooks θα σας ενημερώνουν για όλα τα συμβάντα μέσα στις ομάδες σας. Μπορείτε να τα χρησιμοποιήσετε για να δημιουργήσετε το δικό σας live dashboard και/ή να συγχρονίσετε με τη δική σας βάση δεδομένων.
Όπως αναφέρθηκε παραπάνω, τα δημιουργημένα webhooks από συστήματα αυτοματισμού όπως το Power Automate σας επιτρέπουν να ξεκινήσετε διαδικασίες αποθήκευσης, αποστολές email, αρχειοθέτηση κ.ά., κάτι που σε συνδυασμό με το API παρέχει όλα όσα χρειάζεστε για αυτοματοποίηση διαδικασιών.
Διαθέσιμη είναι επίσης μια συνδρομή websocket σε πραγματικό χρόνο. Αυτή μπορεί να είναι η καλύτερη επιλογή όταν θέλετε ενημερώσεις πελάτη σε πραγματικό χρόνο χωρίς να εκθέσετε ένα endpoint webhook. Το websocket αποκαλύπτει ένα ευρύτερο σύνολο γεγονότων από τα webhooks.
Ναι, τα webhooks μπορεί να φαίνονται δύσκολα, αλλά αξίζουν και είναι εξαιρετικά για την ενσωμάτωσή σας. Συνεχίστε να διαβάζετε.
Τύποι webhook
- Συμβάντα σε πραγματικό χρόνο
- Όλα τα συμβάντα κάθε 6 λεπτά (παλαιό)
- Κατά [συμβάν] (παλαιό)
Για παλαιά webhooks δείτε: legacy webhooks
Τα webhooks χρησιμοποιούνται κυρίως για την λήψη ενός υπογεγραμμένου PDF. Όταν δημιουργείτε το webhook εφαρμόστε το φίλτρο συμβάντος 'Final PDF created'. Στον κώδικά σας, το εισερχόμενο request.body είναι JSON, κάντε ανάλυση (parse) και εξάγετε documentId = ['data']['uuid']. Τώρα εκτελέστε το API query για λήψη του PDF - GET https://eu-api.legalesign.com/api/v1/pdf/${documentId}/.
Πώς να προσθέσετε ή να αφαιρέσετε ένα webhook
Προσθήκη ή αφαίρεση webhook μέσω της web εφαρμογής
Μεταβείτε στο API dashboard και κάντε κλικ στην ενότητα Webhooks. Η φόρμα διαθέτει απλούς ελέγχους για προσθήκη ή αφαίρεση webhooks. Μπορείτε προαιρετικά να περιορίσετε τα γεγονότα webhook σε συγκεκριμένες ομάδες και/ή γεγονότα.

Τα webhooks σας λαμβάνουν συμβάντα από όλους τους λογαριασμούς όπου είστε admin, τόσο σε ανάπτυξη όσο και παραγωγή. Χρησιμοποιήστε το φίλτρο ομίλου για να δημιουργήσετε διαφορετικά webhooks για τις διάφορες ομάδες σας.
Προσθήκη ή αφαίρεση webhook μέσω του REST API
Δείτε την ενότητα 'webhook' στο κάτω μέρος της αριστερής πλοήγησης στην τεκμηρίωση API: REST API webhooks
Προσθήκη ή αφαίρεση webhook μέσω GraphQl
Νέο! Στον GraphiQL Explorer του Legalesign, συνδεδεμένοι με τον λογαριασμό σας Legalesign, έχετε πλήρη δυνατότητα CRUD για webhooks. Τα webhooks μπορούν να απαριθμηθούν ως ιδιότητα του τύπου User, και υπάρχουν μεταλλάξεις (mutations) για createWebhook, updateWebhook και deleteWebhook.
Τι περιέχει ένα webhook;
Ο γρηγορότερος τρόπος για να ελέγξετε τα δεδομένα σας είναι να προσθέσετε ένα webhook, να στείλετε/υπογράψετε/απορρίψετε κάποια δοκιμαστικά έγγραφα στην web εφαρμογή, και μετά να δείτε το αρχείο καταγραφής webhooks στο Legalesign API Dashboard.
Αν χρειάζεστε προσωρινό URL webhook για δοκιμές, δοκιμάστε το ngrok.
Γρήγορος οδηγός για το ngrok: μόλις το κατεβάσετε, εκκινήστε το στο τερματικό με ./ngrok http 80 και θα σας δώσει μια διεύθυνση https. Εισάγετε αυτή ως webhook σας. Τώρα ανοίξτε το http://127.0.0.1:4040. Αυτό είναι, θα αρχίσετε να βλέπετε όλα τα webhooks και τα δεδομένα τους. Ξεκινήστε να στέλνετε και να υπογράφετε δοκιμαστικά έγγραφα. Σημείωση: Το Ngrok μπορεί να επιστρέψει σφάλμα 5XX, οπότε περιμένετε να δείτε πολλαπλές προσπάθειες και μηνύματα σφάλματος καθώς το σύστημα θεωρεί την κατάσταση 5XX ως αποτυχημένη προσπάθεια.
Βεβαιωθείτε ότι ο κώδικας που λαμβάνει webhook επιστρέφει απάντηση επιτυχίας 2XX. Αν έχετε πολλές πιθανές εξαιρέσεις στον κώδικα επιστρέψτε διαφορετικούς κωδικούς κατάστασης 5XX. Τα αρχεία καταγραφής webhook στο API dashboard θα σας υποδείξουν ποια εξαίρεση ενεργοποιήθηκε.
Μορφή webhook σε πραγματικό χρόνο
Η μορφή των δεδομένων μπορεί να είναι μία από δύο σχήματα, είτε 'document' είτε 'recipient'. Εξετάστε το χαρακτηριστικό 'object' για να προσδιορίσετε με ποιο σχήμα ασχολείστε.
Και τα δύο σχήματα έχουν επίσης το χαρακτηριστικό 'event'. Μπορείτε να φιλτράρετε κατά αντικείμενο και προαιρετικά κατά γεγονός όταν δημιουργείτε το webhook.
Ο παρακάτω πίνακας δείχνει όλα τα πιθανά αντικείμενα και γεγονότα. Αυτή η εικόνα δείχνει ένα αντικείμενο εγγράφου (για το γεγονός 'created'). Τα πλήρη JSON σχήματα συνοδεύουν το τέλος αυτού του άρθρου.

Τα αιτήματα φτάνουν ως αίτημα POST που περιέχει JSON. Σημειώστε ότι το περιεχόμενο του 'data' μπορεί να επεκταθεί για να συμπεριλάβει περισσότερα πεδία με την πάροδο του χρόνου.
Χρησιμοποιήστε τα χαρακτηριστικά 'tag'. Μπορείτε να ορίσετε έως 3 ετικέτες (tags) όταν δημιουργείτε ένα έγγραφο. Με τη χρήση tags ίσως να μην χρειάζεται να αποθηκεύετε τα Legalesign IDs. Μπορείτε επίσης να χρησιμοποιήσετε tag για να αποθηκεύσετε ένα μυστικό (secret) προκειμένου να επαληθεύσετε το εισερχόμενο αίτημα (ευχαριστούμε τον Themis γι' αυτή την ιδέα).
Πίνακας πιθανών συνδυασμών για 'object' και 'event':
| αντικείμενο | γεγονός |
|---|---|
| document | created |
| document | rejected |
| document | finalPdfCreated |
| recipient | completed |
| recipient | rejected |
| recipient | emailOpened |
| recipient | visiting |
| recipient | bounced |
| recipient | autoReminderEmail |
| recipient | emailNotification |
Τα περισσότερα γεγονότα συμβαίνουν μόνο μία φορά. Οι εξαιρέσεις είναι visiting, bounced, emailNotification και autoReminderEmail, που μπορεί να συμβούν πολλές φορές.
Μην ξεχάσετε να απενεργοποιήσετε την προστασία CSRF για το view που λαμβάνει αυτά τα POST αιτήματα.
Παρακάτω ένα παράδειγμα αντικειμένου 'recipient', με γεγονός 'bounced':

Παρατηρήστε τα emailBounce και emailBounceMessage στο 'data'. Το 'emailBounceMessage' θα υποδεικνύει τον τύπο της άρνησης (bounce) ως εξής:
- Hard bounce: "Message hard bounced"
- Soft bounce: "Email soft bounced (either out of office or a timeout)"
- Delayed: "Message delayed (check email domain exists)"
Το σχήμα μπορεί να έχει νέα χαρακτηριστικά προστεθεί οποιαδήποτε στιγμή.
Αποσφαλμάτωση webhooks στο API dashboard
Όλα τα webhooks καταγράφονται και μπορείτε να ελέγξετε το περιεχόμενό τους και τον κωδικό κατάστασης http στο API dashboard σας. Για να μάθετε περισσότερα δείτε το Tutorial Dashboard
Χειροκίνητη ενεργοποίηση webhook
Ενεργοποιήστε χειροκίνητα ένα webhook χρησιμοποιώντας τη φόρμα στο κάτω μέρος της σελίδας Webhooks στο Developer Portal.
Βεβαιωθείτε ότι χρησιμοποιείτε πραγματικό αναγνωριστικό παραλήπτη ή εγγράφου, ανάλογα με το γεγονός.
Κωδικοί κατάστασης
Κάντε κλικ σε αυτούς τους συνδέσμους για να δείτε τον πίνακα αναφοράς για κατάσταση εγγράφου και κατάσταση παραλήπτη.
Επαλήθευση webhook
Το webhook υπογράφει το πακέτο δεδομένων με ιδιωτικό κλειδί. Μπορείτε να το επαληθεύσετε με το δημόσιο κλειδί - κατεβάστε το δημόσιο κλειδί.
- Η θέση της συμβολοσειράς υπογραφής είναι στην κεφαλίδα X-Signed-SHA256.
- Τα δεδομένα που υπογράφονται είναι ολόκληρο το request.body (ως συμβολοσειρά).
Η 'υπογραφή' είναι κωδικοποιημένη σε base64. Εδώ είναι παράδειγμα κώδικα επαλήθευσης σε 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');
[1]
Προαιρετικά, είναι διαθέσιμη επαλήθευση με βάση HMAC. Για HMAC, ένα μυστικό κλειδί για τα webhooks σας κοινοποιείται σε εσάς. Η υπογεγραμμένη τιμή θα φτάσει στην κεφαλίδα X-HMAC-SHA256.
Υπάρχουν πολλοί διαδικτυακοί πόροι που δείχνουν πώς να επαληθεύσετε μια τιμή HMAC. Παράδειγμα επαλήθευσης σε 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
Ή παράδειγμα κώδικα Apex για Salesforce για να επαληθεύσετε ένα 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));
Περισσότερα webhooks;
Αν χρειάζεστε περισσότερα webhooks για διαφορετικά γεγονότα ή περισσότερα δεδομένα σε αυτά, επικοινωνήστε μαζί μας και βάλτε το αίτημά σας στην αναπτυξιακή διαδικασία.
Αναφορά σχήματος
Υπάρχουν δύο πιθανά σχήματα, ένα για το αντικείμενο 'document' και άλλο για το αντικείμενο 'recipient'. Και τα δύο σχήματα έχουν κορυφαία κλειδιά 'object' και 'event'. Εξετάστε το χαρακτηριστικό 'object' για να προσδιορίσετε το σχήμα που χρησιμοποιείτε. Ή χρησιμοποιήστε φίλτρο webhook για να επιστρέψει μόνο αντικείμενα document ή μόνο recipient.
Παρακαλώ σημειώστε ότι το σχήμα μπορεί να λάβει νέα χαρακτηριστικά οποιαδήποτε στιγμή (αλλά δεν θα μειωθούν).
1. JSON Σχήμα για το αντικείμενο '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 Σχήμα για το αντικείμενο '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"
]
}