Skip to main content
Developer Tools

Webhooks

Use Webhooks to monitor events.

Before you start

Webhooks are a powerful tool for real-time communication between applications or services. They allow you to receive automatic updates or notifications from DRUO about specific events.

What is a Webhook?

A webhook is a mechanism that allows an application or service to send real-time updates or notifications to another application or service. It enables the automatic delivery of information from one system to another by making HTTP requests to a specified URL, known as the webhook endpoint.

Steps to create a Webhook through DRUO

  1. Log into DRUO portal at https://portal.druo.com

  1. Visit the Webhooks feature page: https://portal.druo.com/webhooks

  1. Click on “Create Webhook Endpoint” button or visit the following page: https://portal.druo.com/webhooks/create

  1. Fill in the form as required:
  • Endpoint URL: The URL to which you want the events to be sent. We recommend testing with https://webhook.site/
  • Description: The name or description of the webhook.
  • Events to listen to: Select the event you want to receive updates for with this webhook endpoint. You can create multiple webhook endpoints if you want to monitor various events. 
  • Secret Key (Optional): A key defined by you that will be used to sign the event payloads with. DRUO will return a signature with every request based on this key in the event’s header after the “X-DRUO-Webhook-Event-Signature” name. 
  • Headers: A series of key-value pairs that we will relay to the Endpoint URL as part of the payload’s header. Might help you further validate the source and characteristics of the incoming message.  

  1. Click on “Add Endpoint”. The system should process the webhook creation, and it should be active by default. 

  1. If you want to make changes to any endpoint at any time, including enabling or disabling it, visit the individual webhook’s details page by navigating to https://portal.druo.com/webhooks and clicking on the desired webhook. This should take you to the detail page where you can access those features via the buttons at the top-right of the page.

Supported Event Types

The following event types are currently supported via the Webhook implementation:

  • Transaction.created
  • Transaction.successful
  • Transaction.failed
  • Transaction.updated
  • Transaction.cancelled
  • Account.created
  • Account.connected
  • Account.connection-failed
  • Account.updated
  • Account.disconnected

Webhook Security: Validating webhook data integrity

Every time a webhook event is processed through the DRUO infrastructure, our system will sign the request based on the payload and the Secret Key provided during the webhook’s setup. This signature will be present in every event sent to the Endpoint URL specified for each webhook and will be present in the header after the “X-DRUO-Webhook-Event-Signature” name. 

If you want to validate the authenticity and integrity of a webhook payload, execute the following calculations. It should output the same exact content than what DRUO provides in the “X-DRUO-Webhook-Event-Signature” header item. 

Steps to create an event signature:

  1. Encode the request’s body sith SHA256 encryption: https://es.wikipedia.org/wiki/SHA-2 
  2. Encode URL + body with the Secret Key provided to our system with HMACSHA512: https://es.wikipedia.org/wiki/HMAC 
  3. Encode everything into en Base64

We recommend using this library to expedite the implementation process: https://www.npmjs.com/package/crypto-js 

Example Requests:

The structure for every object type (Accounts, Transactions, End Users, etc.) stays the same for all related events (created, updated, successful, failed, etc.)

Account Events
{
  "event": "account.connected",
  "data": {
    "code": "A3WFDO8TPD5",
    "type": "DEPOSITORY",
    "uuid": "acc_d283193f-5dac-4733-8a06-65da1f1ed396",
    "last_4": "3434",
    "status": "CONNECTED",
    "remarks": "",
    "subtype": "SAVINGS",
    "end_user": {
      "code": "EUJXRKMEPER",
      "note": "",
      "type": "INDIVIDUAL",
      "uuid": "eur_868d99a5-6578-40cf-8aec-e7a48085fa37",
      "email": "john.doe@example.com",
      "address": {
        "country": "",
        "locality": "",
        "postal_code": "",
        "sublocality": "",
        "address_line_1": "",
        "address_line_2": "",
        "address_line_3": "",
        "administrative_district": ""
      },
      "local_id": "987654321",
      "metadata": null,
      "first_name": "John",
       "last_name": "Doe",
      "organization": "",
      "phone_number": {
        "number": "2312322334",
        "country_code": "1"
      },
      "date_of_birth": "",
      "local_id_type": "NATIONAL_IDENTITY_CARD",
      "creation_source": "MERCHANT_PORTAL",
      "date_created_gmt": "2023-12-15T15:07:33.549Z",
      "date_updated_gmt": "2023-12-15T15:07:33.549Z",
      "local_id_country": {
        "id": "ckviiery8um4f0b86o93ih46l"
      },
      "primary_reference": "",
      "preferred_language": "",
      "secondary_reference": ""
    },
    "metadata": null,
    "institution": {
      "name": "Chase",
      "uuid": "ins_15fed4a9-3839-463f-b38c-a7f73d421d35"
    },
    "capabilities": [
      "PAYMENTS"
    ],
    "creation_source": "CONNECT_LINK",
    "date_created_gmt": "2023-12-15T15:07:33.549Z",
    "date_updated_gmt": "2023-12-15T15:07:33.549Z",
    "primary_reference": "",
    "secondary_reference": "",
    "source_connect_link": {
      "uuid": "clk_aa0a79bb-7959-4b1b-9bbc-383338a49af7"
    }
  }
}
Transaction Events - Sample for transaction.successful
{
  "event": "transaction.successful",
  "data": {
    "code": "T3WFDJWMVJG",
    "type": "PAYMENT",
    "uuid": "trx_c7abf51d-ffe8-474c-85e6-bd166d9592b8",
    "amount": "3324234",
    "status": "SUCCESSFUL",
    "tenant": {
      "uuid": "ten_327fe3ee-8b57-428c-9384-c7a1db052235"
    },
    "remarks": "",
    "currency": {
      "code": "COP"
    },
    "end_user": {
      "code": "EUJXRKMEPER",
      "type": "INDIVIDUAL",
      "uuid": "eur_868d99a5-6578-40cf-8aec-e7a48085fa37",
      "email": "john.doe@example.com",
      "first_name": "John",
       "last_name": "Doe",
      "organization": "DRUO",
      "local_id": "987654321",
      "local_id_type": "NATIONAL_IDENTITY_CARD"
    },
    "metadata": "",
    "fixed_fee": "",
    "total_fee": "",
    "net_amount": "",
    "description": "Test successful transaction 2",
    "variable_fee": "",
    "funding_source": {
      "uuid": "acc_2329cf0d-54e0-4d0f-b505-c78a67fac770",
      "last4": "3434",
      "institution": {
         "name": "Chase",
         "uuid": "ins_15fed4a9-3839-463f-b38c-a7f73d421d35"
      },
    },
    "destination_account": null,
    "creation_source": "MERCHANT_PORTAL",
    "date_created_gmt": "2022-09-23T14:26:28.477Z",
    "date_updated_gmt": "2022-09-23T14:26:28.477Z",
    "auto_send_receipt": "",
    "primary_reference": "",
    "secondary_reference": "",
    "statement_descriptor": ""
  }
}

Possible Webhook Status and Fields

Event Webhook Status Received Status Monitored Fields
transaction successful SUCCESSFUL status
transaction canceled CANCELED status
transaction created PENDING status
transaction failed FAILED status
transaction updated PROCESSING, SUCCESSFUL, REFUNDING, REFUNDED, DISPUTED, FAILED, CANCELED. REVERSED remarks, status, primary_reference, secondary_reference, statement_descriptor, description, net_amount
account connected CONNECTED status
account connection-failed CONNECTION_FAILED status
account created VERIFICATION_PENDING status
account disconnected DISCONNECTED status
account updated VERIFICATION_IN_PROGRESS, CONNECTED, CONNECTION_FAILED, DISCONNECTED, DISABLED remarks, subtype, status, primary_reference, secondary_reference
Close Menu