Contact webhook

Behaviour

In S-360, a contact is a record describing either an individual or a structure being in contact with the institution: clients, prospects, persons inscribed to the newsletter...

When the webhook described in this page is activated, each time a contact is created/updated, S-360 backend calls a given URL transmitting the content of the contact description as a JSON payload. The data in the JSON is the data described by the following method: getContactData of the contact API.

This behavior is asynchronous: the list of updated contact's numbers are stored in a queue, and this queue is processed every M minutes, with M between 1 and 1440.


Synchronization rate

When setting up the webhook, the operator defines:

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

Default values:

  • M=15 minutes
  • S=100
  • bs=1

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 contact will be sent every M minute, 12 times. After all those tentatives, the synchro will be abandonned, but the failed contacts will be logged.

Authentication

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

Modifying the content of the payload

Details

It is possible to select which contact elements will be sent, with the following possible options. (multiple choices are possible)

  • GENERAL: general contact information: first name, last name, date of birth...
  • ADDRESSES: contact addresses
  • AUTHORIZATIONS: contact opt-ins.
  • CRITERIA: other custom information defined by the client (did the contact subscribe to a newsletter? What are his/her centers of interest, what is its fidelity system id...)
  • INDICATORS: computed flags about contacts (.

Other modifications

Other modifications, like changing the structure of the payload, keeping only certain fields, etc., is impossible. If you need a specific payload, you likely want a data export webhook.

The purchase history is not a part of a contact record. If you are researching this, you may be interested in an order webhook

Filtering

A filter can be defined in the interface parameters to decide the transmission of only some specific contacts. This filter parameter contains a string, based on ContactDataResult, like this below:

role=MEMBER;addresses(isMain).zipCode=13.* (only handle all the contacts which role is member and zipCode of main address is starting by 13)

Indicators(*).value=true (if the value of any indicator is true)

The delimiter of each condition in the filter is the character ";".

When a filter is added to the interface parameters, it's important to set the "Details" parameter (possible values in getContactData method).

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 Firehose contact
  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. Select the desired details of the contact to be synced. By default: "GENERAL,ADDRESSES"
  6. Save
  7. In the schedule menu, create a new schedule with a frequency fitting your needs and batch size of 100 (recommanded default value) and a bucket size of 1.

Contact JSON example (with authorizations)

In case of a bucket size greater than one, the payload will always be a list (surrounded with []), even if the payload only contains one element.

{
    "addresses": [{
            "billingAddress": true,
            "contactAddressId": 10228310728251,
            "countryCode": "ES",
            "documentFormattedAddress": "Mrs Liliana CALLEJON\nAvenida Chiquito de la Calzada\nportal 3\n18010 GRANADA\nSPAIN",
            "formattedAddress": "Avenida Chiquito de la Calzada\nportal 3\n18010 GRANADA\nSPAIN",
            "line1": "Avenida Chiquito de la Calzada",
            "line2": "portal 3",
            "localityCriteriaElements": [],
            "main": true,
            "name": "Main address",
            "normalizationRating": "UNKNOWN",
            "normalizationState": "TO_BE_NORMALIZED",
            "shippingAddress": true,
            "street1": "Avenida Chiquito de la Calzada",
            "street3": "portal 3",
            "town": "GRANADA",
            "zipCode": "18010"
        }
    ],
    "advantages": [],
    "authorizations": [{
            "allowed": true,
            "authorizationCode": "CNIL_O"
        }, {
            "allowed": false,
            "authorizationCode": "PARTNER"
        }
    ],
    "contactConnections": [],
    "contactCriteria": [],
    "contactId": 10228310728453,
    "contactNumber": "10912",
    "contactOrigin": {
        "code": "I_BOXOFFICE",
        "translations": {
            "de": "Schalter",
            "ja": "????????",
            "en": "Box office",
            "it": "Box office",
            "fr": "Guichet",
            "ca": "Taquilles",
            "es": "Taquillas"
        }
    },
    "contactQualities": [],
    "creationDate": "2020-10-13T08:57:11.875+00:00",
    "endValidityDate": "2999-12-30T23:00:00.000+00:00",
    "guest": false,
    "hasAdvantages": false,
    "hasWarning": false,
    "indicators": [],
    "individualContact": {
        "active": true,
        "addressSalutation": "Mrs",
        "alternativeEmails": [],
        "cellPhoneNumber": "+34655000321",
        "cellPhoneNumberVerified": false,
        "confidentialityLevelEnum": "FREE",
        "contactNumber": "10912",
        "countryCode": "ES",
        "email": "maria.liliana@yopmail.com",
        "endValidityDate": "2999-12-30T23:00:00.000+00:00",
        "guest": false,
        "handicapType": "HANDICAP/NONE",
        "individualBirthdate": "1989-08-09T22:00:00.000+00:00",
        "individualFirstname": "Liliana",
        "individualGender": "FEMALE",
        "individualLastname": "CALLEJON",
        "individualPreferredLanguage": "en",
        "individualTitle": "MRS",
        "letterSalutation": "Dear Madam",
        "prospect": true,
        "role": "PUBLIC",
        "zipCode": "18010"
    },
    "invalidatedContactQualities": [],
    "loginLastUpdateTime": "2020-10-13T09:40:29.002+00:00",
    "loginLastUpdateUser": "STX_JME",
    "role": "PUBLIC",
    "socialConnections": [],
    "state": "VALID",
    "structureContact": {
        "addressSalutation": "Mrs",
        "allContactNumbers": [],
        "alternativeEmails": [],
        "cellPhoneNumber": "+34655000321",
        "community": false,
        "confidentialityLevelEnum": "FREE",
        "letterSalutation": "Dear Madam",
        "prospect": true,
        "role": "PUBLIC"
    },
    "type": "INDIVIDUAL",
    "createdFrom": {
        "de": "Schalter",
        "ja": "????????",
        "en": "Box office",
        "it": "Box office",
        "fr": "Guichet",
        "ca": "Taquilles",
        "es": "Taquillas"
    }
}