Webhook Operations
This feature is optional. A connector can opt in by providing two endpoints in its configuration — one for subscriptions, and one for parsing. See Webhooks for more details.
Unito can signify its interest in a particular item through a webhook subscription. When that happens, the connector is expected to forward that intent to the provider, and stand ready to parse webhook requests. Below is a list of endpoints a connector must implement in order to support this functionality.
Webhook Subscription
Operation used to manage webhook subscriptions. This endpoints is defined by the webhookSubscriptionsRelativeUrl
property of the configuration file. It accepts a
WebhookSubscriptionRequestPayload
payload.
Multiple subscription requests can be sent for the same item. It is important for this call to be idempotent.
{
"itemPath": "/users",
"targetUrl": "https://api.unito.io/webhooks/receive",
"action": "start"
}
On success, it returns a 204 status code. If a subsequent call is made for the same item, it, too, should return a
204.
Empty
Errors can be of multiple types. As an example, if that particular item doesn't support webhooks.
{
"error": {
"message": "Error while subscribing to webhooks"
}
}
It's on the connector to use the most appropriate error code.
Webhook Parse
Operation used to parse the payload of a webhook received by the provider on behalf of your connector.
This endpoints is defined by the webhookParsingRelativeUrl property of the configuration file.
It accepts a WebhookParseRequestPayload payload.
This call is unauthenticated, and will therefore not contain any credential header.
{
"headers": {
"<header from the provider>": "<value from the provider>"
},
"payload": "<string representing the native webhook payload from the provider>",
"partition": "<partition defined on the credential account for whom the webhook subscription was created>",
"url": "<URL at which this webhook was received, including the query params>"
}
On success, two things can happen. First, if the parsing of the request determined that the webhook pertained to items of interest, one or many WebhookParseResponsePayload are returned.
[
{
"itemPath": "/users/1",
"date": "2023-11-05T08:15:30.000-05:00",
"impactedRelations": [
{
"name": "tasks",
"impactedItems": [
{
"itemPath": "/users/1/tasks/1",
"date": "2023-11-05T08:15:30.000-05:00",
"impactedRelations": []
}
]
}
]
}
]
Otherwise, if no items were detected, a 204 can be returned.
Empty
Multiple types of error can occur. As an example, maybe the payload wasn't properly formed.
{
"error": {
"message": "Error while parsing the content of the webhook"
}
}
It's on the connector to use the most appropriate error code.
Webhook Acknowledge
Sometimes, to officialize a subscription, a provider will issue a challenge to which we need to return specific
values. Other times, a provider will expect a specific status code to validate the proper reception of a webhook
reception.
For these reasons and more, it is possible for a connector to overwrite our usual response. By defining a
webhookAcknowledgeRelativeUrl property in their configuration file, a connector signals its intent to take over the
reception of webhooks.
This call is unauthenticated, and will therefore not contain any credential header.
We strongly suggest not to use this feature unless absolutely necessary.
It accepts a WebhookParseRequestPayload payload.
{
"headers": {
"<header from the provider>": "<value from the provider>"
},
"payload": "<string representing the native webhook payload from the provider>",
"partition": "<partition defined on the credential account for whom the webhook subscription was created>",
"url": "<URL at which this webhook was received, including the query params>"
}
It returns a WebhookAcknowledgeResponsePayload.
{
"statusCode": 234
}
Unito will reply to the provider with the provided response values.