Table of Contents

1 About webhooks
- - 1.1.1 Security
  - 1.1.2 Ordering
  - 1.1.3 Webhook IP addresses
  - 1.1.4 Retry logic
- 1.2 How to start receiving webhooks?
  - 1.2.1 Requirements for webhook endpoint
    - 1.2.1.1 Handling webhook events with HMAC Authentication
- 1.3 Webhook types
  - 1.3.1 Identity Verification (IDV) webhooks
    - 1.3.1.1 IdentityVerification.StatusChanged
    - 1.3.1.2 IdentityVerification.Consented
  - 1.3.2 KYC Identification webhooks
    - 1.3.2.1 KycIdentification.Created
    - 1.3.2.2 KycIdentification.Processed
    - 1.3.2.3 KycIdentification.Approved
    - 1.3.2.4 KycIdentification.Updated
    - 1.3.2.5 KycIdentification.Rejected
  - 1.3.3 KYB identification webhooks
    - 1.3.3.1 KybIdentification.Created
    - 1.3.3.2 KybIdentification.Approved
    - 1.3.3.3 KybIdentification.Rejected
    - 1.3.3.4 KybIdentification.Document.Created
    - 1.3.3.5 KybIdentification.Document.Uploaded
    - 1.3.3.6 KybIdentification.Document.Updated
    - 1.3.3.7 KybIdentification.Document.Deleted
  - 1.3.4 Form webhooks
    - 1.3.4.1 Form.Created
    - 1.3.4.2 Form.Updated
    - 1.3.4.3 Form.Completed

About webhooks

Webhooks enable Ondato to send real-time notifications about changes in your resources. These notifications are sent as POST requests to your server immediately after the event occurs, and the request body includes information about the resource.

Security

Ondato uses HTTPS to transmit these notifications in the form of a JSON payload.

Ordering

Ondato delivers events asynchronously. Therefore, you might receive them out of order and need to handle them accordingly.

Webhook IP addresses

All webhook requests will originate from the following IP addresses:

20.31.10.47
20.31.227.231
20.76.229.117
20.76.229.248
213.226.187.101

Please ensure that you whitelist the above IPs to receive webhook notifications.

Retry logic

Upon sending a webhook notification, we are waiting for a success response for 30 seconds. Otherwise, if your endpoint does not respond, the webhook is queued for retry.

We use an exponential backoff retry policy for event delivery. The attempt to resend the notifications is according to the following schedule on a best effort basis:

10 seconds
30 seconds
1 minute
5 minutes
10 minutes
30 minutes
1 hour
3 hours
6 hours
Every 12 hours up to 24 hours

If the endpoint responds within 3 minutes, we will attempt to remove the event from the retry queue on a best-effort basis. However, duplicates may still be received.

A small degree of randomization is incorporated into all retry steps and may selectively skip certain retries if an endpoint is offline for an extended period or seems overloaded.

The maximum number of retry attempts is 30.

When Event Grid is unable to deliver an event within a specific time frame or after attempting to deliver the event a certain number of times, the event is dropped.

How to start receiving webhooks?

To begin receiving event notifications in your application, you need to follow these steps:

Identify the events you want to monitor.

Please see a full list of events in this section here: Webhooks | 🪄 Webhook types.

Create a webhook endpoint as an HTTP endpoint on your local server.

Handle requests from Ondato.

Deploy your webhook endpoint to make it publicly accessible via an HTTPS URL.

Contact the Ondato support team to register the publicly accessible HTTPS URL and provide a list of events you would like to monitor.

Requirements for webhook endpoint

Ondato needs to know where to send information about events. To receive webhooks, you must create a webhook endpoint and provide us with a publicly accessible HTTPS URL that meets the following criteria:

URL format: https://<your-website-name>/<your-webhook-endpoint>

URL must support POST HTTP method.

URL must be secure (HTTPS protocol).

URL must support one of the available authentication flows:

basic | username, password
oAuth2 | clientID, clientSecret, tokenUrl
HMAC | client-side verification

Handling webhook events with HMAC Authentication

HMAC webhook verification steps:

In a web request, you would receive the Ondato-Signature header.

Request header example:
- Ondato-Signature: t=1712825621, s=7026783cfd8b88a2652f23e789f1ec7de02b7c6ef8362892fe743fead4bab71d

Parse the value t from the header - timestamp

For a given example:
- 1712825621

Get the received body/json string - json

Join to a single string $"{timestamp}.{json}" - message

Using secret, compute HMACSHA256 hash (lower case) for message - computedHash

Parse the value s from the header - signature

For a given example:
- 7026783cfd8b88a2652f23e789f1ec7de02b7c6ef8362892fe743fead4bab71d

Compare the computedHash with the signature - they should match.

Property	Description

Property	Description
`Id`	Webhook ID
`ApplicationId`	Internal ID to identify you in the Ondato system.
`CreatedUtc`	Date and time when the webhook was generated.
`DeliveredUtc`	Date and time when the webhook was delivered.
`IsDelivered`	Status of the webhook if it was delivered or not. Possible values are true/ false.
`Payload`	Depending on the webhook type property, the payload always returns the same information you could obtain from the get endpoint of the resource. For example, the webhook type is `KycIdentification.<event>`, and then the payload will contain information that you can retrieve from the KYC ID endpoint get `/identifications/{id}`. Information about each event payload is here.
`Type`	Type of the webhook. It consists of two parts (the first part identifies the service and the second one, the event): Webhooks \| 🆔 Identity Verification (IDV) webhooks IdentityVerification.StatusChanged IdentityVerification.Consented Webhooks \| 👤 KYC Identification webhooks KycIdentification.Created KycIdentification.Processed KycIdentification.Approved KycIdentification.Updated KycIdentification.Rejected Webhooks \| 🏢 KYB identification webhooks KybIdentification.Created KybIdentification.Approved KybIdentification.Rejected KybIdentification.Document.Created KybIdentification.Document.Uploaded KybIdentification.Document.Updated KybIdentification.Document.Deleted Webhooks \| 🧾 Form webhooks coming soon! Form.Created Form.Updated Form.Completed

Webhook types

Identity Verification (IDV) webhooks

`IdentityVerification.StatusChanged`

{
    "payload": {
        "id": "03be8be3-fbd5-4496-b552-bcd3e4918116"
        }
    }
}

{
    "id": "7a21b0e2-580e-4d2d-8578-00fc32a753ad",
    "applicationId": "44575362-e08e-4f75-b399-00d9d8916552",
    "createdUtc": "2023-01-31T07:25:55.6073016Z",
    "payload": {
        "id": "03be8be3-fbd5-4496-b552-bcd3e4918116",
        "status": "Completed",
        "applicationId": "44575362-e08e-4f75-b399-00d9d8916552",
        "createdUtc": "2023-01-31T07:22:11.313Z",
        "modifiedUtc": "2023-01-31T07:25:55.595Z",
        "setup": {
            "id": "5f16990b-d00a-4ff2-8102-e7b8d5820c28",
            "versionId": "60e8a778-1885-4162-bd58-d8b07bddba2e"
        },
        "step": {
            "kycIdentification": {
                "id": "6df0d302-f0bb-441a-804c-5b114b476fc0"
            },
            "documentSignatures": [],
            "forms": [],
            "consent": {
                "isConsented": true,
                "consentedUtc": "2023-01-31T07:22:25.08Z"
            }
        }
    },
    "type": "IdentityVerification.StatusChanged"
}

Ondato

Webhooks

About webhooks

Security

Ordering

Webhook IP addresses

Retry logic

How to start receiving webhooks?

Requirements for webhook endpoint

Handling webhook events with HMAC Authentication

Webhook types

Identity Verification (IDV) webhooks

`IdentityVerification.StatusChanged`

`IdentityVerification.Consented`

KYC Identification webhooks

`KycIdentification.Created`

`KycIdentification.Processed`

`KycIdentification.Approved`

`KycIdentification.Updated`

`KycIdentification.Rejected`

KYB identification webhooks

`KybIdentification.Created`

`KybIdentification.Approved`

`KybIdentification.Rejected`

`KybIdentification.Document.Created`

`KybIdentification.Document.Uploaded`

`KybIdentification.Document.Updated`

`KybIdentification.Document.Deleted`

Form webhooks

`Form.Created`

`Form.Updated`

`Form.Completed`