Intergiro developer portal

# Events

Events are used to keep track of different actions related to your account. For example, when a transaction is authorized, an AuthorizationCompleted event is created.

A full list of available events and associated endpoints is available in the API reference (opens new window).

# Working with events

You can retrieve all existing events from the API. By default, you will see the most recent events that have occurred.

 




GET /v3/events

Content-Type: application/json
Authorization: Bearer <access_token>

In the response you will receive a list of events and a has_more field, which informs you if there are more events on the next page.

 

















HTTP 200 OK

{
  "data": [
    {
      "created_at": "2022-08-16T12:45:33.000Z"
      "id": "b1ded866-79cc-44d2-aa61-69c26a2f580a",
      "name": "ExampleEvent",
      "payload": {
        "individual_id": "bd4af0ff-0a72-4e09-b247-c6d8c2391496",
        "example_field": "Example value"
      }
    },
    ...
  ],
  "has_more": true
}

# Polling

In order to reliably process events and ensure data consistency, your system must integrate with events by polling the event listing endpoint.

Between each request, your system must retain the cursor (id of the last seen event) in order to retrieve events that occurred after.

 




GET /v3/events?sort_type=ASC&starting_after=0abfb90a-4d6d-451d-bd55-c3e064fb795a

Content-Type: application/json
Authorization: Bearer <access_token>

In this case we have chosen ascending order to retrieve the oldest events first, and we specify the last seen event id.

 















 







 


HTTP 200 OK

{
  "data": [
    {
      "created_at": "2022-08-16T12:45:33.000Z"
      "id": "b1ded866-79cc-44d2-aa61-69c26a2f580a",
      "name": "ExampleEvent",
      "payload": {
        "individual_id": "bd4af0ff-0a72-4e09-b247-c6d8c2391496",
        "example_field": "Example value"
      }
    },
    ...
    {
      "created_at": "2022-08-17T13:51:10.000Z"
      "id": "42943401-f3cb-4c33-a2ed-ffe87055d227",
      "name": "ExampleEvent",
      "payload": {
        "individual_id": "a04bb96a-0203-48a1-8dcf-00a13aaafec9",
        "example_field": "Example value"
      }
    }
  ],
  "has_more": true
}

We save the id of the last event in the list. Since the has_more field has the value true, your system should repeat this process until it is false. At that point, the next polling interval should start with the last saved cursor and begin the process again.

# Webhooks

Webhooks serve as a method of immediate notification about an event being created. They do not contain any data from event payload except for the id, name and createdAt fields.

WARNING

Webhooks should be used as an addition to polling for events, never a replacement.

# Registering new url

In order to register a new webhook URL, make a request to the following endpoint:

 








POST /v3/webhooks

Content-Type: application/json
Authorization: Bearer <access_token>

{
  "url": "https://example.com/webhook-url"
}

You can register at most one webhook URL. Make sure the URL you are registering uses HTTPS.

# Listing webhooks

You can retrieve the webhooks you've registered to verify their URL.

 




GET /v3/webhooks

Content-Type: application/json
Authorization: Bearer <access_token>

Response:

 









HTTP 200 OK

[
  {
    "created_at": "2022-07-01T13:17:19.000Z",
    "id": "a6495db9-8d9d-417d-9918-c5b4a122e712",
    "url": "https://example.com/webhook-url"
  }
]

# Removing registered URL

In order to remove an existing webhook URL, you need to have the webhook ID, which is retrievable by listing webhooks.

 




DELETE /v3/webhooks/a6495db9-8d9d-417d-9918-c5b4a122e712

Content-Type: application/json
Authorization: Bearer <access_token>

# Receiving webhooks

When a new event is created, a webhook is dispatched to the specified URL.

Example webhook payload:

{
  "id": "b1ded866-79cc-44d2-aa61-69c26a2f580a",
  "name": "ExampleEvent",
  "createdAt": "2022-08-16T12:45:33.000Z"
}

To retrieve the event associated with the webhook, use the id from the webhook's body.

 




GET /v3/events/b1ded866-79cc-44d2-aa61-69c26a2f580a

Content-Type: application/json
Authorization: Bearer <access_token>

In the response you will receive a payload field, which contains data relevant to the event.

 




 
 
 
 



HTTP 200 OK

{
  "id": "b1ded866-79cc-44d2-aa61-69c26a2f580a",
  "name": "ExampleEvent",
  "payload": {
  	"individual_id": "bd4af0ff-0a72-4e09-b247-c6d8c2391496",
  	"example_field": "Example value"
  },
  "created_at": "2022-08-16T12:45:33.000Z"
}

# Responding to webhooks

Whenever your system receives a request to the webhook URL, it should acknowledge it by responding with a 2XX HTTP code.

If your system fails to respond with a 2XX HTTP code or if there are any network disruptions, the request will be retried at most 5 times with an initial interval of 1 second and exponential backoff base of 2 seconds (retries will be sent after 1, 2, 4, 8 and 16 seconds).

If the request is not acknowledged with a 2XX HTTP code within those attempts, the webhook will not be sent again.

If your system is receiving an excess of webhook request which it can not handle at a specific time, it can start responding with a 503 HTTP response code. By doing so, the rate at which webhooks are sent will be temporarily slowed down, allowing your system to process them.

← Overview →