HomepageAuthentication

Webhook

In this section, you will find information about how the Webhook of the Unico IDCloud platform works

The respective GetProcess articles for the integration methods describe a way to obtain the status of a process through a call to an endpoint. This enables polling to receive information about the created processes. This means that the endpoint can be called multiple times for the same process to obtain the most recent status.

With the use of webhooks, it is possible to notify a specific endpoint every time the status of a process is changed.

What is a Webhook?​

A webhook is a systemic notification service that allows asynchronous integration between systems, where one system notifies the other through a trigger. This way, webhooks can keep systems updated with the latest information without the need for constant polling for updates.

How to Configure the Webhook

To configure the webhook, the following information is required:

  • Notification URL: This is the endpoint used by By Unico for notifications about status updates.

  • Authentication Type: This is the authentication method used to invoke the endpoint. The following options are available:

    • OAuth2;

    • Basic Authorization;

    • API Key;

    • No authentication.

  • For OAuth2, the following information needs to be provided:

    • Webhook endpoint ;

    • OAuth2 provider URL ;

    • OAuth2 provider ClientId ;

    • OAuth2 provider Secret .

  • For Basic Authorization, it is necessary to send in the format user:pass.

  • For API Key, two formats are possible:

    • header:value, when a specific header name is desired;

    • value, when the desired header is Authorization.

  • Retry Settings: Indicates the number of attempts in case of a failure in calling the endpoint:

    • Maximum number of attempts

    • Interval between attempts (in seconds)

    • Rate Limit: Maximum number of simultaneous sends (maximum: 500).

    • Timeout: Maximum wait time for the endpoint's response (in seconds).

  • Status to be Notified: Currently, the notification is sent whenever the state of a process changes to:

by Unico
by Client

finished: Process finished.

  • 2: Divergence;

  • 3: Completed;

  • 4: Canceled;

  • 5: Error.

Integration with the Unico IDCloud Platform

When configuring a webhook on the platform, you can receive information about processes through notifications sent to an endpoint of the API developed by you to receive these updates.

The information sent by the platform to the API includes:

by Unico
by Client

  • processId: ID of the transaction;

  • state: State of the transaction;

  • flow: Journey of the transaction;

  • lastEvent: Last event triggered (we only return this parameter if the process expires);

  • lastEventDescription: Description of the last event triggered (we only return this parameter if the process expires).

  • id: ID of the transaction;

  • status: State of the transaction.

Click here to see the enum of events that can be return in the webhook
LastEvent
Description

EVENT_STATE_PROCESS_CREATED

Process created

EVENT_STATE_QR_CODE_WAS_READ

QR code was read

EVENT_STATE_SESSION_CREATED

Process started by user

EVENT_STATE_SESSION_AUTHENTICATED

Identity validation step finished

EVENT_STATE_DOCUMENT_STEP_WAS_STARTED

Document step has started

EVENT_STATE_DOCUMENT_PHOTO_TAKEN

Photo of the document taken

EVENT_STATE_DOCUMENT_UPLOADED_FROM_GALLERY

Document uploaded from gallery

EVENT_STATE_DOCUMENT_STEP_WAS_FINISHED

Document step finished

EVENT_STATE_START_SIGNATURE

Signature step has started

EVENT_STATE_DOCUMENT_ACCEPTED

Signature Document accepted

EVENT_STATE_ENVELOPE_OPENED

Envelope opened for signature

EVENT_STATE_DOCUMENT_VIEWED

Document viewed

EVENT_STATE_DOCUMENT_SIGNED

Signature Document signed

EVENT_STATE_SIGNATURE_STEP_FINISHED

Signature step finished

EVENT_STATE_ERROR_ON_DOCUMENT_STEP

Error on document step

EVENT_STATE_ERROR_ON_SIGNATURE_STEP

Error on signature step

Requests​

The request must be a POST method in a REST API, making it easier and more secure to send the information. All fields must be mandatory. The body of the request must accept the transaction ID and the status, as shown in the following example:

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}

About the response status:

Currently, the platform has a set of statuses that may change in the future. Therefore, it is recommended that the statuses you are interested in for taking action be configurable.

Response

The response should be synchronous. The status for successful requests must be in the range of 200 to 299. Any other status is considered a failure, and the platform will then retry the notifications (with exponential backoff between attempts), until receiving a 2xx response or reaching the maximum number of retries.

Rate limit

In order to avoid overloading your resources in situations of high transaction volume, it is possible to specify an upper limit on the number of times the endpoint can be invoked.

Error rate

The error rate (responses outside the [200, 299] range) should always be low. Otherwise, the webhook throughput will be automatically reduced, and this reduction, along with the retry mechanism, may lead to an increase in the execution time of new webhooks.

Idempotency

The current webhook implementation guarantees at-least-once delivery, meaning the same status may be notified more than once. Therefore, the endpoint implementation must be idempotent.

Fallback

In case of any unavailability in the webhook service, it is recommended to have a fallback method in place so that you can continue receiving transaction statuses within the established response time. The query to the endpoint is described in the GetProcess sections for each integration method.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

PreviousCapture standard (without SDK)NextSDK

Last updated