Purpose

    Skarabee develops solutions for real estate brokers. With Skarabee 6 we offer real estate brokers a complete management suite. One of the core functionalities is the possibility to manage the interactions with contacts calling the office. This API gives external VOIP partners the possibility to facilitate this process.

    Technical

    The interaction between the PBX is setup using the webhook method. At the moment an incoming call is received, the PBX processes some parameters and does an HTTP Post to the endpoint - https://voip.skarabee.net/api. The following parameters are required.

    • businessid: Unique identifier for the agency
    • phoneTo: Receiving phone
    • phoneFrom: Originating phone
    • timeStamp: time of the request in seconds since the unix epoch
    • hash: hash of the above fields (see under)

    Skarabee cannot differentiate between an external call or a call originating from within the agency. Additionally we have no notion about redirected calls. It is the responsibilty of the PBX to handle these cases.

    Security

    To avoid the possibility of hijacking the request the following security measures are taken:

    • The endpoint is only available through an TLS connection (https://).
    • The timestamp given must match the timestamp on our server within a certain threshold.
    • The parameters businessid, phoneTo, phoneFrom and timeStamp need to be concatenated and hashed with a private key using HMACSHA256. This private key will be provided when registering for this service and will be unique for every agency.

    Feedback

    A result will be returned containing a status and the corresponding message. The possible statusses are

    • OK
    • NO_HASH_KEY_AVAILABLE (the account is not properly setup)
    • TIMESTAMP_MISMATCH (there is a mismatch between the timestamp provided and the server time)
    • HASH_MISMATCH (the hash provided doesn't match with the arguments)

    Contact

    For questions and demands you can contact our Helpdesk