Webhooks support

Coupler.io supports incoming and outgoing webhooks:

• Incoming webhooks allow launching the importer by API request.
• Outgoing webhooks allow executing an API call after an importer run was finished.

Coupler.io allows you to generate a webhook URL for any importer and add up to 3 outgoing webhooks to any importer. Using webhooks, you can cover different business cases, such as:

• Building a sequence of Coupler.io importers so they execute one after another
• Sending a custom POST request after your importer is executed.
• Notifying your system about importer execution (along the webhook URL that you define, we also send the request body with importer id, status, and error message (if any)).

Request body examples:

=== Successfull ===
{ 
"status":"success",
"workflow_id":"acffe262-756d-11ed-9b52-9f316d1f365f"
}
=== Failed ===
{
"error_message":"1 out of 2 sources have failed. Check details for more information",
"status":"error",
"workflow_id":"d758099c-5513-11ed-bbab-5759c0240d23"
}

How to generate an importer webhook

You need to generate an importer webhook, so that later you can trigger the importer run by sending a POST request with this webhook URL. 

Coupler.io users can generate a webhook for any importer in their account via the following steps:

1. Find the needed importer in the list and click "See details":
2. Scroll down until the “Importer webhook” section and click the "Generate webhook" button:
3. Copy generated webhook URL by clicking on the "Copy" icon:

How to change the importer webhook URL

There are situations when you may want to change the webhook URL. For example, you shared it with a team member who is  leaving the company and you need to ensure their access is revoked. You can do this from the importers' page.

To change the webhook, please follow the next steps:

1. Find the needed importer in the list and click "See details":
   
2. Scroll down to the “Importer webhook section”  and click the "Update webhook" icon:
3. Confirm that you want to change the webhook URL by clicking the “Change” button:
   
4. Copy the new webhook URL by clicking on the "Copy" icon::

How to trigger an importer run with a webhook

Once you’ve set up the importer webhook URL, you need to execute a POST request with that URL to run the importer. 

For example, the webhook URL for your importer is as follows: https://app.coupler.io/w/execute/1a53f56c-4001-11ed-97b8-afbee7b3887b-4f8f92db-572d-488f-abcc-8f80e5c61141, so to trigger the importer, you need to execute the following request:

curl --request POST 'https://app.coupler.io/w/execute/1a53f56c-4001-11ed-97b8-afbee7b3887b-4f8f92db-572d-488f-abcc-8f80e5c61141'

If execution starts - you will receive the response status code 200 and the following response body:

{
    "id": "<execution_id>",
    "last_run_at": "YYYY-MM-DDThh:mm:ss",
    "last_error_message": null or "<error_message>" if any
}

If the response is different, it could be that the webhook URL is outdated, or you have reached your account limits (e.g., runs), etc. Please contact Coupler.io support, so we can help you define the root cause and fix the issue.

How to set up outgoing webhooks

To set up an outgoing webhook, please follow these steps:

1. Open the view page of the importer you want to use as a trigger.
2. In the "Outgoing webhook" section at the bottom of the page, enter the webhook URL (you can add up to three different webhook URLs)

And that's it!

Please be aware that for the proper functioning of the webhooks, your URL should be:

• Valid (starting from https:// or http://).
• Unique  (You cannot add the same webhook URL twice to the same importer. You can, however, use the same webhook URL across different importers).

If you enter a valid URL, but the request itself is wrong (requires GET method, has missing parameters, etc.), Coupler.io will still send this request, but you will not get the correct result.

FAQ

Can I trigger a run for the same importer manually, on schedule, and by webhook?

Yes. You can, for example, run an importer according to a certain schedule and when you need, also launch it manually and/or via a webhook. The only difference in such runs is that scheduled runs do not refresh your destination data in case the source has no new/updated data (read more here).