Receive a Callback From Evrotrust

Receive a Callback From Evrotrust


Info

This guide explains how to set up and handle callbacks from Evrotrust. Callbacks are asynchronous notifications sent by Evrotrust to your server when certain events occur (e.g., a document is signed, expires, or is rejected). These notifications allow your application to react in real-time without polling the API.

The process relies on server-to-server communication, with no built-in security headers in the callback requests. Security is achieved through IP whitelisting and proper endpoint validation. Always implement this on a secure, server-side endpoint (not client-side).

Prerequisites

  • Webhook Endpoint: A publicly accessible URL on your server that can handle HTTP POST requests (e.g., https://yourdomain.com/evrotrust-callback).

  • Server Environment: Support for handling JSON payloads (e.g., Node.js, Python, PHP, Java).

  • Security: Use HTTPS for your endpoint. Whitelist Evrotrust's IP addresses to restrict access.

  • Logging and Error Handling: Implement logging for debugging and retries.

1. Set Up the Callback URL in Your Requests

  • When making API requests to Evrotrust that support callbacks (e.g., initiating a document signing process), include a urlCallback parameter in the request body or query string.

  • This parameter should point to your server's webhook endpoint.

  • Example in JSON request body:

     Important: Depending on the request - you will receive the actual callback on the following adresses:
         - For Signing via application: <urlCallback>/document/ready
         - For OTP signing: <urlCallback>/document/offline/ready

2. Handle Incoming Callback Events

  • Evrotrust triggers a callback when an event occurs, such as:

    • Document signed successfully.

    • Document expired.

    • Document rejected.

    • Other status changes (consult Evrotrust API docs for full event list).

  • The callback is an HTTP POST request to your specified urlCallback.

  • No Security Headers: Requests do not include authentication headers. Rely on IP whitelisting (see Step 5) and validate the payload internally (e.g., check if transactionID matches an active transaction in your database).

3. Parse the Callback Payload

  • The payload is in application/json format.

  • Expected fields:

    • transactionID: String or integer – The unique ID of the transaction (matches the one from your initial request).

    • status: Integer or string – The status code of the transaction (e.g., "signed", "expired", "rejected"). Refer to Evrotrust documentation for exact codes.

    • rejectReason: String (optional) – Only present if the status is "rejected". Describes the reason (e.g., "user declined").

Parameter

Description

Type

transactionID

The unique ID of the transaction (matches the one from the response of your initial request)

string

status                                             

The status code of the transaction. Refer to Evrotrust documentation for exact codes

int

rejectReason

Only present if the status is 3 (rejected). Describes the reason (e.g., "user declined")

String

Example payload:

  1. {
  2.   "transactionID": "961546252836",
  3.   "status": 3,
  4.   "rejectReason": "Refuse to sign"
  5. }

  • In your endpoint, read the request body, parse the JSON, and process accordingly (e.g., update your database, notify users).

4. Respond to the Callback

  • Evrotrust expects a HTTP 200 OK response to confirm receipt.

  • Timeout and Retries: The request times out after 30 seconds if no 200 is received. Evrotrust will retry up to 2 more times (total 3 attempts) before stopping.

  • Best practices:

    • Respond quickly (under 30 seconds) to avoid retries.

    • If processing takes time, acknowledge with 200 immediately and handle asynchronously (e.g., queue the task).

    • Return a simple empty body.

5. Secure Your Endpoint with IP Whitelisting

  • Evrotrust sends callbacks from specific IP addresses:

  • Configure your server or firewall to only accept requests from these IPs.

Troubleshooting

  • No Callbacks Received: Verify urlCallback is set correctly and your endpoint is accessible. Test with tools like Postman.

  • Retries Occurring: Ensure your endpoint responds in <30 seconds. Check server logs for delays.

  • Security Issues: Ensure you are whitelisting the proper IP for each environment. Check if you are still blocking requests.

  • API Documentation: Consult Evrotrust's official docs for exact status codes, additional fields, or event types.



    • Related Articles

    • Implement Document Signing via Evrotrust Application

      This guide provides a step-by-step process for integrating the Evrotrust API to enable document signing via the Evrotrust mobile app. The flow involves checking user status, sending documents for signing, handling callbacks, checking status ...

    • User Guide - Evrotrust Support Portal - Zoho Desk

      Тable of Contents Summary & Overview Purpose of This Guide How to Use the Evrotrust Support Portal 1. Registration, Login & Forgotten Password 1.1 First-Time Access 1.2 How to Log In 1.3 How to Reset a Password 2. Navigating the Portal 2.1 Home ...

    • Availability Report

      Attached, you can find the availability report for the services by month:

    • Document Decryption Guide

      This guide provides a step-by-step explanation of the decryption process for the encrypted file in the result of document/download. The scheme combines RSA (asymmetric encryption) to encrypt a symmetric key and AES (symmetric encryption) in CBC mode ...