Data Export Webhook

Table of Contents

Behaviour

This webhook interface is linked to a specific Data Export Query.

The query Q is executed every M minutes. For each new line produced by the query, the webhook is called.

S-360 does POST the line of the query in the form of a flat JSON object, which parameters are named according to the columns of the query result.

Synchronization rate

When setting up the webhook, the operator defines:

  • the frequency M: the list of pending updates will be processed every M minutes.
  • the batch size S: during each process, S items will be processed.
  • the bucket size bs: a payload POST-ed to the remote URL will consist of a maximum of bs items.

Default values:

  • M=15 minutes
  • S=500
  • bs=10

What is a flat JSON object?

It is an object with no hierarchy.

Example 1

Posting access control ticket checks.(as returned to S-360 by the access control system)

[{
    "ticket_check_id":10228845124401,
    "movement_id":10228844462196,
    "ticket_id":10228844446468,
    "barcode":"072212349924430836880155",
    "access_time":"2023-02-09 18:25:10",
    "check_flow":"IN",
    "result":"OK",
    "failure_reason":"NO_FAIL"},

    {"ticket_check_id":10228845124402,
    "movement_id":10228844462195,
    "ticket_id":10228844446467,
    "barcode":"321488720810990025100150",
    "access_time":"2023-02-09 18:25:02",
    "check_flow":"IN",
    "result":"FAIL",
    "failure_reason":"NO_MORE_ENTRY_ALLOWED_TODAY"}]

Example 2

Posting data about updated products in the catalog:

[{
    "id": 10223696442077,
    "externalDescription": "A very important match",
    "state": "SUSPENDED",
    "eventId": 10228253332100,
    "start": "2023-01-28 17:00:00.0",
    "season": "Summer season",
    "hostTeam": "FC Triffoully",
    "opposingTeam": "SGS Essen",
    "Day": "MATCH_DAY/1/4",
    "venue": "Stadion Somewhere",
    "city": "Triffoully"
}
]

Example 3

Posting simple contact data (this could replace the contact webhook if only very simple data are needed)

[
    {
        "socialConnections.providerUserReference": "362639947",
        "contactNumber": "3346662",
        "creationDate": "2022-11-01T05:53:22.530+00:00",
        "role": "PUBLIC",
        "type": "INDIVIDUAL",
        "individualFirstname": "James",
        "individualLastname": "Bond",
        "cellPhoneNumber": "+4436411225",
        "email": "james.bond@mi6.gov.uk",
        "individualCountryCode": "UK"
    },
    {
        "socialConnections.providerUserReference": "362639949",
        "contactNumber": "3346663",
        "creationDate": "2022-11-01T17:51:22.530+00:00",
        "role": "PUBLIC",
        "type": "INDIVIDUAL",
        "individualFirstname": "Felix",
        "individualLastname": "Leiter",
        "cellPhoneNumber": "+1555342552",
        "email": "felix.leiter@cia.gov",
        "individualCountryCode": "US"
    }
]

Which data can be extracted?

Any data that is available in S-360 database can be provided via this webhook and any reasonably simple flat JSON object can be produced.

There are the following restrictions:

  1. The data export query must be written by S-360's services team, at a cost (depending on its complexity). Please provide us the data that you would like to receive so that we can study your needs.
  2. The activation of the notification can be triggered by events affecting only 1 entity. For example, it is possible to trigger contact export based on contact change OR on the fact that this contact did an order, but not both at the same time. (If you need both, it will be two different data streams)

URL and HTTP method

The callee must provide an URL which will accept POST requests containg the JSON payload described below and return 200 when accepted.

If the URL returns values (an id, a message...), those values will be ignored.

If the URL returns an error, the same item will be sent every M minute.

Authentication

It is possible for S-360 to process an authentication on the remote URL. Here are the supported authentication protocols:

Setup in backend

  1. Ask for a proxy opening for the destination URL.
  2. In organization/tools/external interfaces create a new interface of type Export/Webhook
  3. Paste the url in the Url field
  4. Choose the authentication mode : NONE, BASIC_AUTH, API_KEY
    1. NONE : nothing else to do
    2. BASIC_AUTH : put the login in the login field, the password in the password field
    3. API_KEY : put the name of the header in the login field, the key in the password field
  5. Enter the name of the query to use in the query fields.
  6. Enter 10 into the Bucket size field.
  7. In the schedule menu, create a new schedule with a frequency fitting your needs and batch size of 500