Intergiro developer portal

# 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 /v1/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.

WARNING

The company can register only one Webhook.

# Listing webhooks

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

 




GET /v1/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 /v1/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 /v1/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": {
  	"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.

← Events →