Inbound Webhooks

Inbound Webhooks (Incoming HTTP requests) allow your integration to receive data at a unique URL from third-party systems. This lets those systems automatically send messages to your integration whenever something happens on their end. These user-defined callbacks, combined with custom payloads, enable a wide range of automation scenarios.

For example, converting article text to an MP3 audio file (text-to-speech) can take time. You can create a webhook to receive a notification as soon as the MP3 is ready.

To use this feature, start by creating a custom event. Custom events are private to your organization and can be used in any way you choose.

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

Up first: Local development

Make sure you have your local environment and integration set up. You can also reference Creating handlers to receive events with IFX.

Webhooks require a custom event, but we can start locally before touching sandbox or production.

Create a handler to receive the custom event. You can name it whatever you like.
/src/eventsRouter.js
```
{
  "demoHandler": [
    "custom:demo_event",
  ]
}
```
/src/eventsHandlers/demoHandler.js
```
const demoHandler = async (event) => {
  console.log("event", event)
}
```
Start up the local server

npm run localTestingServer
Send a request

To run and test your custom event integration locally, key and body are required to invoke your integration. When using the “live” Webhook URL, any JSON payload is accepted.

POST http://127.0.0.1:8080/ifx/local/invoke/
```
{
  "key": "custom:demo_event",
  "body": {
    "custom": "some custom data"
  }
}
```
Verify the handler was reached by checking the console log in the terminal.

You can choose to deploy the starter bundle right away to test it in action, or finish writing your full integration before deploying to the sandbox. Next, we’ll cover the steps for moving to sandbox.

Getting to sandbox

All aspects of integration management, including custom events and webhooks, can be managed using IFX’s CLI commands or APIs.

From your local machine, build and zip the bundle
Upload, deploy, promote to sandbox

Create a custom event on sandbox:

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

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

Create a webhook that will trigger the event created above:

POST /ifx/api/v1/admin/events/custom/custom:demo_event/webhooks
```
{
  "description": "Here is my webhook"
}
```
Webhooks-to-custom events are one-to-one, so you cannot create a second webhook for the same custom event.

Subscribe the integration to your custom event

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

{
  "eventName": "custom:demo_event",
  "enabled": true,
  "integrationName": "integrationName"
}

Send a POST request with a custom payload to the webhook URL you received when you created the webhook.
```
{
  "test": "testing"
}
```
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:
Verify expected behavior by viewing logs or other means such as updated ANS.

View all webhooks

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

Code 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

Use one webhook per third-party integration

It is highly recommended to use a single webhook for each third-party integration.

There may (and should) be occasions where you need to regenerate a Personal Access Token (PAT) for a webhook. By using one webhook per third-party integration, you avoid having to update multiple external systems whenever you rotate a token.

Assigning each webhook to a single third-party source also helps:

Isolate potential misuse, minimizing the impact of an exposed or misused token.
Enable faster remediation, making it easier to revoke and replace a token without disrupting other systems.

Rate limits

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.

Webhooks return only an HTTP status code

Webhooks are designed to be asynchronous, fire-and-forget triggers. When a webhook is invoked, the receiving integration processes the event independently and does not send data back in the response body. IFX returns only an HTTP status code e.g., 200 Accepted to confirm that the event was delivered to the downstream endpoint.

This design ensures:

Reliability and performance — downstream processing does not block delivery and does not increase latency for other callers.
Security and predictability — avoiding arbitrary response bodies reduces risk of leaking sensitive data and keeps request/response contracts stable.
Industry-standard behavior — leading webhook providers (such as GitHub, Slack, and AWS EventBridge) also expect receivers to respond only with an HTTP status code, not with a custom response body.

For debugging and validation, you can add console.log to your handler and see this data in the logs. As always, do not log sensitive data.

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.

Messages with a priority of ingestion are not supported, which is commonly used for content migrations or bulk-updating content.

If you are subscribed to story:update and send updates for that story from your integration back to Draft API, this will re-send story:update creating an infinite loop.

To avoid this it is crucial to include an HTTP header Arc-Priority: ingestion so that it will be ignored when it is coming back around.

const headers = {
  'Authorization': `Bearer ${arcPat}`,
  'Arc-Priority': 'ingestion'
};

If you are using Migration Center, please reference Sending Multiple ANS Objects to Arc XP Services Using Migration Center .

Receiving Data

Webhooks 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.

FAQ

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 properly. 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.

Have a feature request or suggestion? Let us know on Our Ideas Portal.