# Webhooks

Iteras has support for getting immediate notification when an event happens inside Iteras. The information is delivered directly to your server as webhooks.

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

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. Otherwise anyone could POST data to your endpoint.

When you have the data, process it as explained in the next section. Once you've finished processing, your web server must reply to the POST request with a HTTP 200 status code. 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.

# Processing the data conveniently

The events come as a list of objects, like this:

[
  {
    "event": "customer:created",
    "event_id": 531,
    "timestamp": "2025-01-15T18:32:00",
    // ... 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 of one of the customer's subscriptions. Instead of having to go through the API to retrieve that 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": "2025-01-15T18:32:00",

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

    "prefetch": {
      "customers": [
        {              // current data for customer 141280
          "id": "141280",
          "data": {
            "created": "2025-01-15T18:32:00",
            "name": "Jane Doe ",
            // ...
          }
        }
      ]
    },
  },
  // ... more events
]

The prefetched data comes in the same format as when you retrieve customer data to make it easier 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 save it locally and send a 200 reply back. If you need to do further processing, schedule it to be done after replying.

The reason is that the webhook endpoint must reply within reasonable time. You can see the precise time inside the webhook settings in Iteras.

There should be plenty of time to update a local database, 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 you have trouble keeping up anyway, lower the maximum number of events sent per delivery.

Note that due to possibility of resending, you may end up getting the same event twice. So you might benefit from keeping track of the latest event ID that you have succesfully processed. Then you just skip any up to that ID.

# Robustness and error handling

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.

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.

You can setup an email address in the error monitoring section in Iteras to get notified upon failure. When the issue is fixed, simply turn on delivery again inside Iteras.