Add section to API Handbook for webhooks

[dacook]

Admin Only: Language Checklist for when this Update is Complete

• Catalan
• English
• French
• German
• Italian
• Portuguese
• Russian
• Spanish
• Turkish

---

Tell us what you would like to see

Which language version of the User Guide are you viewing? English

Description
A new feature has been released to set up webhooks triggered by an event (order cycle opened). I'd like to document this so that it is easy to discover and refer to.

This is different but similar to the API. Currently we have no documentation about API features, but I think it's time to create a section for this, to make it possible for any users to discover what options they can start to use.
Currently there's an API Handbook at https://ofn-user-guide.gitbook.io/ofn-api-handbook/. This section should be added there.

Which section would you like the new content to be added to?
I'm open to suggestions, but I think there should be a new top-level section (same level as "OFN API V1").
I can imagine it would be useful to create "how to" guides as well (eg how to send an email notification when order cycle opens).

In which instance(s) do you know that users are adversely affected by this information being missing from the User Guide in its current form?
Unknown

How would you rate the impact of the current version of the User Guide on your instance?

• High volume of support queries
• Occasional support query
• Prevents/deters new enterprises from setting up
• User misunderstandings around this issue result in those enterprises affected moving away from OFN...

Suggested Draft of content to be added
Added to comment below.

I would like to be part of a larger User Guide group who write this section

• yes
• no

[dacook]

Suggested Draft of content to be added

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

(i) To set this up you require API access granted by an administrator.

Permitted users may subscribe to certain events, 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:

{
  "id": "374e0a40-f1d4-410c-9dc3-965baddde66b",
  "at": "2023-02-07 17:12:45 +1100",
  "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"
  }
}

To set this up, go to Account > Developer Settings > Webhook Endpoints.

Select from the available events, and enter the unique endpoint URL provided by the other system. Click create.

Once created, the other system will receive a request on this URL each time the event occurs, with a payload containing relevant information.

Error handling

If there is an error sending the webhook, it will be retried later. We use Sidekiq's default schedule, which means it will perform 25 retries over approximately 20 days, with an exponential backoff.
This means if the receiving system is unavailable for a time, the webhook will still be delivered but at a delayed time.

[dacook]

I just discovered the OFN API handbook here: https://ofn-user-guide.gitbook.io/ofn-api-handbook/

This suggested content should go in there. But I can't find it in GitHub so I'm not sure how to suggest it, so I'll rename and keep this issue open for the moment.

[dacook]

Just found some old terminology notes I had written which I might incorporate:

Endpoint: A URL that the OFN system will send a HTTP POST to whenever a certain event occurs
Event: Something that happens which may be initiated by time (eg order cycle opening) or a user action. The type of event has a name, eg "order_cycle.opened".
Payload: the data about that event, in a certain JSON format.

[dacook]

Submitted here: https://app.gitbook.com/o/-L9rgjXCVdbnhSow2XnR/s/Nv32980j4B1B2UoS6UMi/~/changes/47/webhooks/overview/~/comments/ovtmQ8ElBPlkLCb7B935