Webhooks
After a document has been signed it can be delivered back to your system.
Definition of termsβ
The following keys are needed to work with webhooks.
companyKey
the baseKey used to identify a company.flowKey
There can be many flows each with its own delivery methods registered.webhookSignatureKey
The key used to validate that Taktikal sends the webhook data.
Webhookβ
The data Taktikal sends via webhook are wrapped in a WebhookEventPayload
object that has an Id
, EventData
, and EventSignature
See example data
below.
EventSignature
is used to validate that Taktikal is the one who sends the data.TimeStamp
andGUID
hashed with thewebhookSignatureKey
to create aSignature
. If theSignature
that is calculated is not a match to the value in the event, it was not sent by Taktikal. For convenience we also supply theSignedData
property which has already concatenated TimeStamp and Guid into a single valueEventData
contains allsignee
that signed the document and all their personal information provided in this process. The signed document is stored as a base64 string in the fieldSignedDocument
Taktikal will send a POST request to the registered URL when an event occurs and expects an HTTP Status code 200 Response. For all other response codes, Taktikal Will retry two more times. Unless an HTTP Status code 406 (not accepted) is received that marks that we will not try again.
Webhook event typesβ
Taktikal sents out webhook events for Created
, SignedDocument
, AllSigned
,
Canceled
or Expired
,
Event name | Event description | contains document | integer value |
---|---|---|---|
Created | This is an event that is triggerd when a new signing process is created. | π΄ | 11 |
SignedDocument | This is an event that is run for each signing except the last one. | π΄ | 1 |
AllSigned | This is an event triggered on the last signature. | β | 2 |
Canceled | This is an event that is run when a signing process is canceled. | π΄ | 5 |
Expired | each signing process needs to be signed within 30 days. If it expires this event will be triggered | β | 6 |
Register a webhookβ
Webhooks can be managed via the API. All routes can be viewed in Swagger here.
AttachmentReferencesβ
A signing process can have AttachmentReferences. Each AttachmentReference has
AttachmentType
. That can be any of the values in the table
AttachmentType | Value | Description |
---|---|---|
Unspecified | 0 | this is the most common value. It's used for all regular attachments. |
EvidencePage | 10 | for standart signatures and advanced signatures, an EvidencePage is generated and seald by Taktikal |
PepPdf | 20 | a PDF file contaning PEP and sactions results for a signee in an AML process that is seald by Taktikal |
PepJson | 30 | a JSON file contaning PEP and sactions results for a signee in an AML process |
Verification | 40 | for advanced signatures all attachments related to identify the signee have this attachment type. |
XmlForSealing | 50 | an xml attachment that is selead and added as an embedded attachment to the PDF when it's signed |
VerificationMedia | 60 | images that are collected during the ID verification process |
CompanyInfo | 70 | Company report used in AML processes. compare the answeres to the official company data from the goverment |
Recommended approachβ
When you receive a webhook event, we recommend that you offload it to your own
message queue service for further processing and respond to us with Http status
code 200
.
This minimizes the risk of data loss as any error during processing of message can be seen and replayed within your own infrastructure.