1. Home
  2. Docs
  3. Developer Documentation
  4. XcooBee SDKs
  5. PHP SDK

PHP SDK

Download and Source

https://github.com/XcooBee/xcoobee-php-sdk

Composer/Packagist:

https://packagist.org/packages/xcoobee/xcoobee-sdk

License

Published under: Apache v 2.0

SDK

The XcooBee PHP SDK is a facility to abstract lower level calls and implement standard behaviors.
The XcooBee team is providing this to improve the speed of implementation and show the best practices while interacting with XcooBee.

Generally, all communication with XcooBee is encrypted over the wire since none of the XcooBee systems will accept plain traffic. All data sent to XcooBee from you and vice versa is also signed using PGP protocols. The data packets that you will receive are signed with your public key and the packages that you send are signed with your private key.

If you need to generate new PGP keys you can login to your XcooBee account and go to the settings page to do so.

XcooBee systems operate globally but with regional connections. The SDK will be connecting you to your regional endpoint automatically.

There is more detailed and extensive API documentation available on our documentation site.

Call limits

If you are using developer accounts please be aware that there is a call limit. This is normally 120 calls per hour or 600 calls per 24 hour period.

For subscription accounts your call limits are determined per your account and contract. If you hit your call limits, you will need to contact your account manager or support to increase them.

Once you have exceeded your call limits, your call will return status 429 too many requests.

Logs

Like all standard transactions API calls are logged on the XcooBee network. They have the same time to live (TTL) constraints.

Getting Started

API endpoint

To use the test API endpoint, please set an environment variable XBEE_STATE=test.

example:






export XBEE_STATE=test

or if you are on Windows:






set XBEE_STATE=test

using PHP:






putenv('XBEE_STATE=test');

The config object

The config object carries all basic configuration information for your specific setup and use. It can be transparent handled by the SDK or specifically passed into every function.
The basic information in the configuration is:

  • your api-key from XcooBee
  • your api-secret from XcooBee
  • your pgp-secret/passphrase either from you or XcooBee
  • your default campaign Id from XcooBee

The SDK will attempt to determine the configuration object based on the following schema:

1.) Use the configuration object passed into the function.

2.) Use the information as set by the setConfig call.

3.) Check the file system for the config file (.xcoobee/config)

About PGP Secret and password

All PGP data is optional to the configuration object. If you do not supply it the SDK will skip decryption/encryption steps. You will have to do these outside the SDK and supply or process the data yourself.

Currently all events that you subscribe to from the XcooBee network will communicate with and extra layer of PGP encryption. You will need to decrypt the payload using your PGP private key.

If you provide the PGP private key and its passphrase to the SDK, the SDK will automatically decrypt the payload and provide content for further processing.

setConfig(configModel)

The setConfig call is the mechanism to create the initial configuration object. You can use it multiple times. Each time you call you will override the existing data. The data once set will persist until library is discarded or clearConfig is called.






apiKey => the api-key as supplied by XcooBee account apiSecret => the api-secret (downloaded when api key was created at XcooBee) pgpSecret => the pgp-secret key either generated by XcooBee or supplied by you pgpPassword => the pgp-password supplied by you campaignId => the default campaign Id from your campaign on XcooBee pageSize => pagination limit (records per page), default based on recordset, max possible is 100

clearConfig()

Removes all configuration data in the configuration object.

config on file system

XcooBee SDK will search the file system for configuration info as last mechanism. You should ensure that the access to the config files is not public and properly secured. Once found the information is cached and no further lookup is made. If you change your configuration you will need to restart the process that is using the SDK to pick up the changes.

We recommend that you also look into how to encrypt the contents of these files with OS specific encryption for use only by the process that uses the XcooBee SDK.

The files will be located inside your home directory in the .xcoobee subdirectory. Thus the full path to config are:

/[home]/.xcoobee/config => the configuration options

/[home]/.xcoobee/pgp.secret => the pgp secret key in separate file

on Windows it is in the root of your user directory

/Users/MyUserDir/.xcoobee/config => the configuration option

/Users/MyUserDir/.xcoobee/pgp.secret => the pgp secret key in separate file

The initial content of the config file is plain text, with each option on a separate line.

example file:






apiKey=8sihfsd89f7 apiSecret=8937438hf campaignId=ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be pgpPassword=somethingsecret pageSize=10

options:






apiKey => the api-key apiSecret => the api-secret campaignId => the default campaign id pgpPassword => the password for your pgp key pageSize => pagination limit

Standard Responses

The XcooBee system has two modes of response. One, based on standard web HTTP REST API calls, and, two based on asynchronous webhooks (HTTP POST) when events occur.

The response package is structured into envelope and details. The envelope contains operational results such as error or success and time stamps. The detail contains associated return data for your call. XcooBee SDK will always return a value, even if it is an error object. In short, there is always a return. The absence of a return should be treated as error in standard responses.

Webhook (HTTP POST) responses are based on asynchronous practices. The XcooBee system will reach out and inform you about event. These are covered further down in this document.

Success package

Object structure for response:

  • time
  • code (response code 200-299)
  • request_id (the associated request reference)
  • result (data object)
    • the result object is signed with your public PGP key if this is an event response.

Error package

Object structure for error response:

  • time
  • code (response code: 300-500)
  • request_id (the associated request reference)
  • errors (array of error objects with data: message, detail)

Webhook Events (HTTP POST)

Via the SDK, you can subscribe to many events that are available on the XcooBee network. As these occur at different times you will need to be able to accept communication from XcooBee via HTTP POST to a target site that is available via the Internet.

As an alternative to a public site, you can use the Event Polling mechanism as described later in this document to receive this communication.

Methodology

If there is a delayed response, the call will be accepted and the response returned via the HTTP POST event configuration. Your system should have a web-endpoint that is reachable by the XcooBee system for the event responses. A webhook is not a REST endpoint (HTTP – verb based).

The webhook system uses HTTPS POST calls to send information to you in response to event in XcooBee processing. You subscribe to events by calling the System->addEventSubscription() method. More information and examples available in examples/addEventSubscription.php in this project.

Calling systems should be aware that there may be delays and that responses may be returned in different order from the call order.

Webhook Delivery Signature

HTTP POST payloads that are delivered to your webhook’s configured URL endpoint will contain several special headers:

Header Description
XBEE-EVENT Event type that triggered the delivery. E.g. ConsentApproved
XBEE-TRANS-ID A GUID identifying this event
XBEE-SIGNATURE The HMAC hex digest of the response body*
XBEE-HANDLER Name of a function that was configured as a handler for current event type
  • The XBEE-SIGNATURE header will be sent if the webhook is configured with a secret. The HMAC hex digest is generated using the sha1 hash function and the secret as the HMAC key.

Implementing Webhook Acceptance

You can implement your own webhook acceptor and handle all information as passed to you that way. Github has a good standard review of this process. Github Webhook Examples

Use SDK Tools for Event Handling

The SDK offers a methodology for accepting webhooks (HTTP POSTS) that:

  • validates the content and signatures
  • handles encryption / decryption
  • manages the event handlers

This is a multi step process that is actually simple in the final implementation. It involves three parts:

a) determine how you wish to receive events

b) register your event subscription and handler pairs

c) process inbound events

a Determine how to receive events

You have two options on how to receive events from the XcooBee network. Event HTTP post (webhook) or Event polling.

HTTP POST

When elect to use HTTP POST, you need to supply a web accessible system or endpoint with which the XcooBee network can directly communicate. This occurs normally over port 443 (HTTPS/TLS). When an event occurs on the XcooBee network, for example, a user changes their consent agreement, the XcooBee network will trigger an event to this endpoint.

You specify your target URL during the setup of your consent campaign in the XcooBee UI. You cannot change or set it via the SDK.

Event Polling

As an alternative you can poll events from your system on a regular interval. This is useful when you do not have a web accessible system or are in development mode. The SDK has a supporting method getEvents which allows you to retrieve all events that you have subscribed to that occurred during the last 72 hours.

For testing purposes you will also find a single page application (SPA) in the poller directory of this project. It will poll and resubmit events for you to internal network endpoints.

b Register your Event Subscription and Handler Pairs

This is one of the simpler parts. As you subscribe to events using the addEventSubscription() you also supply the PHP function that you wish to invoke when such an event is returned as function argument. See the function definition for more information.

c Process Inbound Events

The easiest way to process inbound event is to invoke the handleEvents([event]) method of the System class.

Normally this is included in your site endpoint (page) that receives the HTTP POST from XcooBee. If you do event polling, you can pass the full POST body as event to the function.

This handleEvents will validate call and call your handlers that you have declared in step b

Standard Endpoint (target Url)

If you choose to accept events via webhook (HTTP POST), we recommend the that you create a standard endpoint to handle all communication. During the processing of this page you can, then, call the handleEvents() method.

The standard endpoint to create would be /xbee/webhook

If your site runs on localhost the fully formed webhook target URL would be http://localhost/xbee/webhook.

Depending on your framework and syntax library this may also be:

  • /xbee/webhook.php
  • /xbee/webhook.jsp
  • /xbee/webhook.cfm
  • /xbee/webhook.aspx

System Calls

ping([config])

Can be called to see whether current configuration will connect to XcooBee system. This will return an error if your API user does not have a public PGP key on its profile.

options:






config => optional: the config object

response

standard JSON response object

  • status 200 if success
  • status 400 if error

addEventSubscription(arrayOfEventAndHandlerPairs[, campaignId, config])

You can register subscriptions to hooks by calling the addEventSubscription function and providing the event (as specified in this document) and handler pairs eventname => handler.

There is no wildcard event subscription, however, you can add many handlers at one time.

Example:






$xcoobee->system->addEventSubscription( ['ConsentDeclined' => 'declinedHandler'], 'ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be', $config );

This will subscribe you on the XcooBee system to receive ConsentDeclined events for the ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be campaign and call your handler named declinedHandler(event) when such an event occurs.

All event data is attached to the events object in the function calls.

No response is expected directly from any of the event handlers so returns are void/null.

options:






arrayOfEventAndHandlerPairs => array with event and handler maps campaignId => optional: the campaign Id to use if not default config => optional: the config object

response

standard JSON response object

  • status 200 if success
  • status 400 if error

listEventSubscriptions([campaignId, config])

list current subscriptions.

options:






campaignId => optional: only get subscriptions for the campaign id config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data will contain current subscriptions dataset: type, campaign, last
  • status 400 if error

deleteEventSubscription(arrayOfEventNames[, campaignId, config])

delete existing subscriptions.
If you do not supply a campaign Id the event will for the default campaign Id will be deleted. If the subscription does not exists we will still return success.

options:






arrayOfEventNames => array with eventnames to be unsubscribed campaignId => optional: the campaign Id to use if not default config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data will contain the number of deleted subscriptions
  • status 400 if error

triggerEvent(type[, config])

Trigger test event to configured campaign webhook. The structure will be the same as real event (with encrypted payload and HMAC signature).
Also you will receive XBEE-TEST-EVENT header, which indicates that event is test. If campaign webhook is not configured, you’ll receive an error.

options:






type => name of event config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data will contain test event data
  • status 400 if error

handleEvents(events)

This function does not require a call to the XcooBee API. It is rather the handler for calls that you recceive from XcooBee via webhooks as outlined previously.

You should embed this function into the route/endpoint processor that is invoked when XcooBee posts back to you one of the events that you have registered for earlier. You can find out which events these are by calling the listEventSubscriptions method.

The webhook post will be validated in this method and if post is valid, we will look into the registered events and further invoke the mapped placeholder function for each event that was created with the addEventSubscription() method.

Optionally, the events data object may be passed along with the data from the HTTP header and POST call.

There is two modes of operation for handleEvents().

a) Without function parameter events:

When you call handleEvents() without an events function argument, the method will look for the event data in the webhook (HTTP POST) stream. Verify the HTTP signatures against expected signatures and then process the event.

b) With function parameter events:

In case where you poll for events from XcooBee seperately you can call handleEvents(events) directly with the events. If you supply the events specifically, the method will not look for HTTP POST header variables for verification and instead will directly process events as provided.

options:






events => optional: array of objects with HTTP post data

response

  • no response, since this is an internal call to the mapped event handlers

getEvents([config])

In cases where you are not able to use direct webhook posts to your sites, for example you are in development or your system cannot be accessed via the Internet directly, you can pull your events from XcooBee.

If you are using pull based access make sure that you do not have an Endpoint defined in your campaign as XcooBee will otherwise attempt to post to the endpoint and register an error. Without a campaign endpoint, XcooBee will save events that you subscribe to and respond to your pull requests.

You have 72 hours to pick up the saved events. Once pulled events will be deleted. So please make sure that you save them if you need to replay them.

Your pull intervall should not be more than 1 getEvents() call per minute otherwise HTTP error 429 will be returned. We recommend every 62 seconds to avoid any timer issues.

options:






config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data will contain array of events since last call
  • status 400 if error

Consent Administration Calls For Consent

getCampaignInfo([campaignId, config])

get basic info on campaign (setup, datatypes and options). The information will not return the users registered with the campaign.

options:






campaignId => optional: the campaign Id to use if not default config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data will contain campaign data object
  • status 400 if error

listCampaigns([config])

get all user campaigns

options:






config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data will contain array of campaign objects
  • status 400 if error

getDataPackage(packagePointer[, config])

TO BE IMPLEMENTED:

When data is hosted for you at XcooBee you can request the data package each time you need to use it. You will need to provide packagePointer. This call will only respond to authorized call source.

options:






packagePointer => the packagePointer for the data you wish to receive config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data will contain requested data object
      The SDK will decrypt this for you if it has access to PGP keys otherwise you have to decrypt this object
  • status 400 if error

listConsents([statusIds, config])

Query for list of consents for a given campaign. Company can get general consentId for any consent that was created as part of a campaign. This is a multi-page recordset. Data returned: consentId, creation date, expiration date, xcoobeeId

possible response/filter for status:

0=pending, 1=active, 2=updating, 3=offer, 4=cancelled, 5=expired, 6=rejected

options:






statusIds => optional: array of numbers, one of the valid consent statuses, if not specified all will be returned config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain consent data object: consent_id, status_id, date_c, date_e, xcoobee_id
  • status 400 if error

getConsentData(consentId[, config])

Query for a specific consent given. Company can get consent definition for any consent that was created. The data normally has three areas: Who, what data types, what the uses are, how long.

options:






consentId => the consent Id for which to retrieve information config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain consent data object: user, datatypes, consenttypes, expiration
  • status 400 if error

getCookieConsent(xid[, campaignId, config])

This is a shortcut mechanism to query the XcooBee system for existing user consent for consent type Website Tracking (1400), Web Application Tracking (1410) for specific use data types (application cookie (1600), usage cookie (1610), and advertising cookie (1620)). We will retrieve only active consent for the cookies on the website identified in the campaign Id and return whether user has agreed to any cookies.

note:

  • Your site in your campaign has to match the origin of the call since we do not use PGP encryption in this call for speed.
  • The user has to be logged in to XcooBee

The return is a CSV list like this:

  • application,usage,advertising

options:






xid => XcooBee Id of the user to check for consent campaignId => optional: the campaign id to use if not default config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain website cookie consent CSV: application,usage,advertising
  • status 400 if error

requestConsent(xid[, refId, campaignId, config])

Sends out the consent or consent and data request to a specific user using the data in the campaign. The campaign definition determines what data (only consent or consent + data) we will ask from the user.

options:






xid => XcooBee Id of the user to check for consent refId => optional: reference Id generated by you that identifies this request to you. Max 64 chars. This will returned to you in event response campaignId => optional: the campaign id to use if not default config => optional: the config object

When user responds to the consent request a webhook will fire from XcooBee to the identified endpoint in the campaign. The SDK does not allow Endpoints to be created or changed. Please use the GUI.

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

confirmConsentChange(consentId[, config])

Use this call to confirm that data has been changed in company systems according to change requested by user.

options:






consentId => the consent for which data is to be confirmed config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

confirmDataDelete(consentId[, config])

Send by company to confirm that data has been purged from company systems

options:






consentId => the consent for which data has been deleted config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

setUserDataResponse(message, consentId[, requestRef, filename, config])

Companies can respond to user data requested via this call. Standard hiring points will be deducted for this. The call will send a message to user’s communication center. You also need to send a file with user’s data in order to close data request.

options:






message => the text to be sent to the user as user data consentId => the consent for which data has been deleted requestRef => optional: unique identifier of the data request, you will receive this on `UserDataRequest` event filename => optional: pointer to the file which contains user's data config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

These are events returned to your endpoint as part of user working with their consent center. All endpoints are determined inside each Consent Campaign.

ConsentApproved

Fires when a consent request is approved. The consent object is returned.
It contains:

  • consent reference
  • data types
  • consent types
  • expiration

ConsentDeclined

Fires when a consent request is declined. You should remove user data and sent a XcooBee confirmation via confirmDataDelete().
The data submitted contains:

  • consent reference

ConsentChanged

Fires when consent is changed. A standard consent object is returned.
It contains:

  • consent reference
  • data types
  • consent types
  • expiration

ConsentNearExpiration

Fires when an active consent is about to expire (inside 30 days). This is not exactly 30 days as the XcooBee system processes may push this slightly. You should plan ask for renewal of consent if you like to use the user data longer.
It contains:

  • consent reference
  • expiration

ConsentExpired

Fires when consent expired. You should remove user data and sent XcooBee confirmation via confirmDataDelete().
It contains:

  • consent reference

UserDataRequest

Fires when user is making a request to extract their current data from your systems. This is to meet data-portability of GDPR. You should create data extract and send it to the User’s XcooBee box. You can do so hiring the xcoobee-data-response bee with the GUID reference of the request.
It contains:

  • consent reference
  • xcoobeeId

UserMessage

Fires when user is sending you a message regarding a consent request.
Your campaign can enable/disable this feature in the campaign options. You can respond to this using a sendUserMessage() call.
It contains:

  • consent reference
  • xcoobeeId
  • message

Consent Administration Calls For Data

This section covers events that are used in connection with gathering data and consent at the same time.

Data Events (webhooks)

Events submitted by XooBee to your system.

DataApproved

Fires when consent is given and data has been supplied by user. A standard consent object is returned.
It contains:

  • consent reference
  • data types with data
  • consent types
  • expiration

DataDeclined

Fires when user declined to provide data and consent. You should remove user data and sent XcooBee confirmation via confirmDataDelete().
It contains:

  • consent reference

DataChanged

Fires when data or consent is changed. A standard consent object is returned.
It contains:

  • consent reference
  • data types with data
  • consent types
  • expiration

DataNearExpiration

Fires when an active consent is about to expire (inside 30 days).
This is not exactly 30 days as the XcooBee system processes may push this slightly.
You should plan ask for renewal of consent if you like to use the user data longer.
It contains:

  • consent reference
  • expiration

DataExpired

Fires when data has expired. You should remove user data and sent XcooBee confirmation via confirmDataDelete().
It contains:

  • consent reference

UserDataRequest

Fires when user is making a request to extract their current data from your systems.
This is to meet data-portability of GDPR.
You should create data extract and send it to the User’s XcooBee box.
You can do so hiring the xcoobee-data-response bee with the GUID reference of the request.
It contains:

  • consent reference
  • xcoobeeId

UserMessage

Fires when user is sending you a message regarding a consent request.
Your campaign can enable/disable this feature in the campaign options. You can respond to this using the sendUserMessage() function.
It contains:

  • consent reference
  • xcoobeeId
  • message

Message

sendUserMessage(message, consentid, [breachid], [config])

This function allows you to send a message to users. You can communicate issues regarding breach, consent, and data this way. It will create a threaded discussion for the user and for you and append to it this message.

options:






message => the text to be sent to the user as user data, can be html formatted. Max 2000 characters consentId => the consent Id that triggers the notification breachId => optional: related breach, user will receive a message with proposed actions declared in a breach config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

getConversations([config])

This function allows you to get a list of discussions with users regarding breaches, consents and so on.

options:






config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

getConversation(userId[, config])

This function allows you to get full discussion with selected user.

options:






userId => the user Id config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

Breach

The breach API is the main way to interact with users during breach. The breach declaration and initial notifications occur in the UI.

Breach Events (webhooks)

BreachPresented

Fires when user has opened breach advice.
It contains:

  • consent reference

BreachBeeUsed

Fires when user has used a bee that you have identified in the breach advice.
It contains:

  • consent reference
  • bee reference

UserMessage

Fires when user is sending you a message regarding a consent request.
Your campaign can enable/disable this feature in the campaign options. You can respond to this using the sendUserMessage() function.
It contains:

  • consent reference
  • xcoobeeId
  • message

Bee API

The Bee api is the principal interface to hire bees. Most of the times this will be accomplished in two steps. In the first step you upload your files to be processed by bees using uploadFiles() call. If you did not specify an outbox endpoint you will also have to call the takeOff() function with the processing parameters for the bee.

The immediate response will only cover issues with files for the first bee. If you want to be informed about the progress of the processing you will need to subscribe to events.

listBees(searchText[, config])

This function will help you search through the bees in the system that your account is able to hire. This is a simple keyword search interface.

options:






searchtext => string of keywords to search for in the bee system name or label in the language of your account config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain basic bee data: bee-systemname, bee-label, bee-cost, cost-type
  • status 400 if error

uploadFiles(files[, endpoint, config])

You use the uploadFiles function to upload files from your server to XcooBee. You can upload multiple files and you can optionally supply an outbox endpoint. If you have an outbox endpoint you do not need to call the takeOff function as the endpoint already specifies all processing parameters. If your subscription allows you can configure the outbox endpoints in the XcooBee UI.

options:






files => array of strings with file pointers to the file store, e.g.: `c:\temp\mypic.jpg` or `/home/mypic.jpg` endpoint => optional: the outbox endpoint, e.g. `marketing data` or `POS drop point` config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

takeOff(bees, options[, subscriptions, config])

You normally use this as follow up call to uploadFiles(). This will start your processing. You specify the bee(s) that you want to hire and the parameter that are needed for the bee to work on your file(s). If you want to be kept up to date you can supply subscriptions. Please note that subscriptions will deduct points from your balance and will cause errors when your balance is insufficient.

This is the most complex function call in the Bee API and has multiple options and parts.

a) parameters
b) subscriptions
c) subscription events

options:






bees => array of bee system names (e.g. "xcoobee_digital_signature_detection") as key and their parameters as value options => general options subscriptions => optional: the subscriptions array. Specifies the subscriptions config => optional: the config array

a Parameters

Parameters can be bee specific or apply to the overall job.

specific bee parameters example:






$bees['xcoobee_testbee'] = [ 'height' => 599, 'width' => 1200, ];

Overall job parameters to be used for the hiring are specified with the process prefix including destinations (recipients) to which you wish to send the output of the processing.

general process parameters example:






$options['process']['userReference'] = 'myownreference'; $options['process']['destinations'] = ['email@nullmysite.com', '~jonny']; $options['process']['fileNames] = ['filename.png'];

Bee parameters that are specified require the bee name prefix. If the bee name is xcoobee_testbee and it requires two parameters height and width then you will need to add these into an associative array inside the parameters array with a key of bee name.

b Subscriptions

Subscriptions can be attached to the overall process. You will need to specify a target, an events and a handler argument at minimum. The target endpoint has to be reachable by the XcooBee system via HTTP/S POST. The events determines which events you are subscribing to.

Thus the three keys for each subscription are:

  • target => string with target endpoint URL
  • events => array with life-cycle events to subscribe to
  • handler => required: the PHP function that will be called when we have bee API events

The HMAC signature will assume your XcooBee Id as the shared secret key and will use the the PGP public key to encrypt the payload. Without this you are still using SSL encryption for the transfer.

To subscribe to overall process events, the keyword process needs to be used. The subscription details need to be attached as subkeys to it.

Remember that subscriptions deduct points from your balance even if they are not successful so please validate that the endpoints you specify in target are valid.

Example of subscription on the overall process.

subscriptions example:






Process Subscriptions: $subscriptions['target'] = "https://mysite.com/beehire/notification/" $subscriptions['events'] = ["error", "success", "deliver", "present", "download", "delete", "reroute"] $subscriptions['handler] = "myBeeEventHandler"

c Subscription events

The event system for bees uses process level events.

Process Level events

  • error
    • There was an error in the processing of the transaction. If there are multiple errors each of them is send in separate post.
    • Event type sent in POST header – ProcessError
  • success
    • The overall transaction completed successfully
    • Event type sent in POST header – ProcessSuccess
  • deliver
    • Is there was a transfer of a file, the file was delivered to the inbox of the recipient
    • Event type sent in POST header – ProcessFileDelivered
  • present
    • If there was a transfer of a file, the file was seen by the user
    • Event type sent in POST header – ProcessFilePresented
  • download
    • If there was a transfer of a file and the user downloaded the file
    • Event type sent in POST header – ProcessFileDownloaded
  • delete
    • This event occurs when user deletes the file
    • Event type sent in POST header – ProcessFileDeleted
  • reroute
    • When user has automated inbox rules and the document has been sent to a different place a reroute event is triggered
    • Event type sent in POST header – ProcessReroute

Event payload examples:

  • success event example:





{ "date": "2017-12-04T16:50:40.698Z", "file": "myImage.jpg", "userReference": "88jenr", "recipient": "~john873", "event": "success", "eventLevel": "bee", "source": "Block4-post", "beeName": "xcoobee_image_resizer", "transactionName": "9SDd8ccb" }
  • error event example:





{ "date": "2017-10-24T15: 22: 39.209Z", "file": "myhome2.jpg", "userReference": "no-reference", "recipient": "no-recipient", "event": "error", "eventLevel": "bee", "source": "Block4-post", "beeName": "xcoobee_image_converter", "message": "Timeout error on container process", "transactionName": "0P4bbee" }

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

Inbox API

The inbox API governs the access to your inbox. You can list, download, and delete items from your inbox.

listInbox([config])

This method will present a paged list of inbox items that you can download. The listing will be for the user connected to you API key. You cannot check any other user’s inbox using this method. You can return up to 100 items in one call.
Calling this method more than once per minute will result in HTTP 429 error (exceeding call limits).

You will the following data-points:

  • messageId
  • sender
  • fileName
  • fileSize (in bytes)
  • receiptDate
  • expirationDate
  • downloadDate

Inbox items are listed in order of arrival with most recent items first.

options:






config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain list of inbox items in array: messageId, sender, fileName, fileSize, receiptDate, expirationDate, downloadDate
  • status 400 if error

getInboxItem(messageId[, config])

This method will return a file and file meta tags. Upon first downloaded, the downloadDate for the item will be populated.

options:






messageId => the message Id for the file to be downloaded config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain the file and file_meta object (userRef, fileType, fileTags)
  • status 400 if error

deleteInboxItem(messageId[, config])

This method will delete a file that corresponds to your messageid. If the file does not exist, an error will be returned.

options:






messageId => the message Id for the file to be deleted config => optional: the config object

response

standard JSON response object

  • status 200 if success:
    • data object will contain true
  • status 400 if error

User API

getUserPublicKey(xid[, config])

Retrieves a user’s public PGP key as published on their public profile. If the user chose to hide it or the user is not known, it returns null.

example:






getUserPublicKey('~XcooBeeId');

options:






xid => XcooBee Id of the user to get their public PGP key config => optional: the config object

response

public PGP or null

Troubleshooting

Error 401

Certain SDK calls require authorized origins.

You may receive 401 error responses from XcooBee if your API call originates from an unauthorized domain or IP. Please make sure you registered your domain in your XcooBee campaign CallBack URL option.

Error 429

Once you have exceeded your call limits, your call will return status 429 too many requests. Please update your subscription or contact support.

Was this article helpful to you? Yes No

How can we help?