Skip to content
Arc XP
Product Documentation

IFX Inbound Webhooks

Before Inbound Webhooks, Integrations were able to receive only event data from internal Arc XP applications, but now you can close the loop on your external integrations and perform updates within your Arc XP environment when something relevant happens in an external system.

Inbound Webhooks (Incoming HTTP requests) offers a way for your integration to receive data to a unique URL from third-party integrations. This enables these third parties to automate messages to your integration when something happens in their system. These user-defined callbacks coupled with custom payloads open a wide variety of use cases.

For example, converting an article text to audio mp3, or text-to-speech, can take time. You can create your Webhook to receive a notification when the mp3 has successfully been created.

To enable this functionality, you can create custom events. These events are private to your organization, and you can use them however you choose.

This document provides tips and best practices for using Inbound Webhooks as well as additional resources.

Things to Know

Rate Limit

Webhooks are subject to a rate limit of 15/s.

Webhook requests must be authenticated using bearer tokens

A bearer token is sent through a header with a request to the Webhook. If the third party does not support this method of authentication, IFX webhooks cannot be used at this time. Generate a restricted PAT for your webhook: How to Create a Restricted-Access Developer Token.

What request types are accepted?

Webhooks can only receive POST requests

Avoiding Infinite Loops

Do not use a Webhook to trigger an integration which is listening for the same event. This will create an infinite loop. In the case you ever do have an infinite loop, you can stop it by unsubscribing from the event that is triggering your integration.

Receiving Data

  • These are designed for you to receive notifications with information from third parties and is not meant to support passing of massive amounts of data.
  • Can receive any custom payload under 256 KB.
  • Are subject to a default rate limit of 15 requests per second. Note that other downstream systems such as Draft API have their own rate limits.

Does this affect my integration usage count?

Yes, webhook requests do count towards an integration’s usage. Be mindful of if/when to tell the third party to trigger a webhook. For example, do you want every single story update to go from IFX to the third party, or just in certain situations? These decisions will impact the number of requests the third party sends to IFX.

What about failures or guaranteed delivery of messages to IFX?

Your integration should handle errors. For example, using the Node.js language, you should use a “try/catch”, where on catch (error) you can decide what action you would like to take, such as a Slack notification.

Basic Workflow

This assumes you are already familiar with and have created an integration. A more detailed example is provided below.

See Swagger Doc

1. Create a custom event

POST /ifx/api/v1/admin/events/custom

{
  "eventName": "custom:myeventname",
  "description": "Here is my description"
}

2. Create a Webhook

POST /ifx/api/v1/admin/events/custom/custom:myeventname/webhooks

{
  "description": "Here is my webhook"
}

There may (and should) be occasions where you need to regenerate a PAT for a Webhook. So that you do not have to update multiple external systems, use only one Webhook per Third-Party Integration. Sharing the Webhook with a single source also helps to silo any misuse and enable quick remediation.

3. Subscribe the integration to your new event

POST /ifx/api/v1/admin/events/subscriptions

{
  "eventName": "custom:myeventname",
  "enabled": true,
  "integrationName": "myIntegrationName"
}

You can have up to five integrations subscribe to a custom event. Webhooks-to-custom events are one-to-one, so you cannot create a second webhook for the same custom event.

4. Send a request to your new endpoint

POST /ifx/api/v1/webhook/12345678-1945-4ab1-a665-794c1c29edf2 using a custom payload. You must authenticate using a Restricted Developer Token. See How to Create a Restricted-Access Developer Token to do this. At the bottom of the Create restricted access token page, you will see Platform APIs. Select Full Access for IFX Webhook:

Platform APIs

{
  "test": "testing"
}

Listing Your Webhooks

You can view a list of your webhooks and their associated custom events with GET /ifx/api/v1/admin/events/custom/webhooks

Local Invocation versus Webhook URL Invocation

The local development payload is slightly different than what sends to your Webhook URL. This is because the Webhook URL performs a reverse lookup and maps the event to your integrations.

To run and test your custom event integration locally, use the same endpoint http://127.0.0.1:8080/ifx/local/invoke/ using your custom payload, but adding a few necessary parameters. For local development, key and body are required to invoke your integration. When using the Webhook URL, any JSON payload is accepted.

Local example payload:

{
  "key": "custom:sendToPipedream",
  "body": {
    "test": 123
  }
}

Webhook URL example payload:

{
  "test": 123
}

Example

This example guides you through creating a very simple integration so you can practice and see it in action, Download the source code: https://github.com/arcxp/ifx-example-webhooks. The README walks you through development.

Best practices

Storing sensitive data.
As always, never store sensitive information such as access tokens in places other than Secrets Manager

Use one Webhook per third party.
There may (and should) be occasions where you need to regenerate a PAT for a Webhook. So that you do not have to update multiple external systems, use only one Webhook per Third-Party Integration. Sharing the Webhook with a single source also helps to silo any misuse and enable quick remediation.

Help us improve our documentation! Let us know if you do not find what you are looking for by posting suggestions to Our Ideas Portal.