> For the complete documentation index, see [llms.txt](https://ofn-user-guide.gitbook.io/ofn-api-handbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ofn-user-guide.gitbook.io/ofn-api-handbook/webhooks/overview.md).

# Overview

Webhooks are a way for the OFN system to send messages to another system that supports it.

{% hint style="info" %}
To set this up you require API access granted by an administrator.
{% endhint %}

Permitted users may subscribe to certain ***events***, by providing a unique URL address (or ***endpoint***) for the other system. When the relevant event occurs, a message is sent with a ***payload*** containing data about the event. This message is sent as a HTTP request to the provided URL, with a JSON body in a format such as this:

```json
{
  "id": "374e0a40-f1d4-410c-9dc3-965baddde66b",
  "at": "2023-02-07 17:12:45 +1100", // this is expected to be updated to ISO format (as seen below)
  "event": "order_cycle.opened",
  "data": {
    "id": 3813,
    "name": "Another test order cycle",
    "orders_open_at": "2023-02-07T17:10:00.000+11:00",
    "orders_close_at": "2023-02-08T12:00:00.000+11:00",
    "coordinator_id": 2515,
    "coordinator_name": "David's Dev Shop"
  }
}
```

#### Error handling

If there is an error sending the webhook, it will be retried later. We use Sidekiq's [default schedule](https://github.com/sidekiq/sidekiq/wiki/Error-Handling#automatic-job-retry), which means it will perform 25 retries over approximately 20 days, with an exponential backoff. 

Therefore if the receiving system is unavailable for a time, the webhook will be delivered at a delayed time.