# Change webhooks

Iteras has support for getting immediate notification when an event happens inside Iteras. The information is delivered directly to your server through the webhook infrastructure.

Note that it is also possible to retrieve events directly through the API. This can be useful if you need the data, but don't want to set up a server endpoint in your end, and can live with some latency.

The webhook infrastructure is often used to synchronize part of the data from Iteras to an external system. We have a guide on how to make a robust synchronization.

# Setting up a webhook inside Iteras

Start by setting up a new webhook inside Iteras.

You need to provide a URL to deliver the events to. For a live setup, this must be an HTTPS URL to ensure that personal information is not transmitted unencrypted.

You can filter on what categories of events you're interested in, set max number of events per delivery, and enable prefetching of the concerned objects to make it easy to process the events.

Once the webhook is created and enabled, Iteras will keep track of which events have been sent through it. When new matching events occurs, they will be delivered. The events are always sent in order.

The webhook user interface allows you to rewind the webhook, and start and stop delivery, both of which can be useful during testing.

# Setting up the receiving endpoint

You need to to set up a web server endpoint to receive the data.

Iteras delivers the events by making a POST request with the list of events as JSON. Unless you're on a test account, the server must support HTTPS, and the URL must resolve to a public address. Iteras does not follow redirects, so the delivery URL must be the final endpoint.

The request includes a Authorization: Bearer [token shown in the webhook setup], like this:

POST /webhook-for-iteras/ HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer 50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c

[...]

Make sure you check that the Bearer token is valid each time you receive data so that nobody else can feed data into your system.

When you have the data, store and process it as explained in the next section. The actual processing should be done in a separate task after storing it. The reason is that events may come in bursts: a change applied to a whole segment of subscriptions or a renewal run may produce events for many customers within a few minutes, and an endpoint that processes inline while Iteras waits for the reply will time out and be resent to.

Once you've finished storing the data, your web server must reply to the POST request with a HTTP 200 status code and a special header X-Iteras-Webhook-Key. The reply can otherwise be empty - the important thing is that you let Iteras know that you've received the sent events. Otherwise they'll be resent.

X-Iteras-Webhook-Key should be set to the response key found in the webhook settings inside Iteras. If the header is missing or wrong on a 200 reply, Iteras deactivates the webhook so that the data isn't delivered to the wrong endpoint. Here's an example:

HTTP/1.1 200 OK
X-Iteras-Webhook-Key: abc9123df43fdaf545fddfs4bdfa34123b32b3213b2123b123240

The response key is different from the Bearer token: the Bearer token is something Iteras sends and you verify, while the response key is something you send back and Iteras verifies.

There's a test button in the webhook settings page for an easy check that your endpoint does the right thing.

# Storing and processing the data conveniently

The events are split up in chunks, with each chunk being sent as a list of objects, like this:

[
  {
    "event": "customer:created",
    "event_id": 531,
    "timestamp": "2026-04-28T08:44:21",
    // ... a few more attributes depending on the event
  },
  // ... more events
]

The specific attributes sent depend on the event, and are for the most part internal to Iteras.

In many cases, what you really want to know is the new state of the object, e.g. the customer or a subscription. Instead of having to go through the API to retrieve that information immediately afterwards, you can enable prefetching in the webhook. Then Iteras will the attach the information about the concerned objects directly, like this:

[
  {
    "event": "customer:created",
    "event_id": 531,
    "timestamp": "2026-04-28T08:44:21",

    "customer_id": "141280",
    // ... a few more attributes depending on the event

    "prefetch": {
      "customers": [
        {              // current data for customer 141280
          "id": "141280",
          "data": {
            "created": "2026-04-28T08:44:21",
            "name": "Jane Doe ",
            // ...
          }
        }
      ]
    },
  },
  // ... more events
]

The prefetched data comes in the same format as when you retrieve customer data to make it trivial to reuse code. The webhook setup inside Iteras allows you to set the parameters you'd otherwise give directly to the API.

So now you have the data in a convenient way. What do you do with it?

The answer is that you store it locally and send a 200 reply back. If you need to do further processing, schedule it to be done after replying. The webhook endpoint must reply within reasonable time. You can see the precise time inside the webhook settings in Iteras.

Given the configurable chunk sizes, there should be plenty of time to update a local database or a file or queue system, but if you need to access an external service that is either unpredictable or just generally slow, the delivery code in Iteras may end up timing out and resending. So that kind of work must be done in a task that runs independently of the webhook endpoint code.

If your endpoint has trouble keeping up anyway, lower the chunk size to get fewer events sent per delivery. You can use the test button in webhook settings to experiment with this.

Since events might be resent, you may end up getting the same event twice. If you keep track of the latest event ID succesfully processed, you can just skip any up to that ID.

# Going live

Once you've set up the webhook and start relying on it, it's important that the whole process is robust. That's why it's important to stick to the plan given in the previous section - it handles most errors automatically. If your webhook endpoint is down, crashes or does not reply in time, Iteras will schedule resends later. That way brief outages are repaired automatically.

In case the resends ultimately all fail, delivery to the webhook is automatically turned off in Iteras. So setup an email address in the error monitoring section in Iteras so somebody hears about it if delivery fails. When the issue is fixed, simply turn on delivery again inside Iteras.