Webhooks

Last modified: 6 years ago

1. What are Webhooks?

Webhooks are a tool for retrieving and storing data from a certain event. They allow you to register an http:// or https:// URL where the event data can be stored in JSON format.

2. How it works?

We are sending 'POST' request to your URL with 'JSON' webhook data for the following events:

topic.created
topic.accepted
topic.satisfaction_changed
comment.created
comment.accepted
comment.deleted

3. Data example

{    "hook": "topic.created", 
    "created": "2014-04-25T04:17:38.306Z",
    "data": {
        "id": 439181,
        "header": "Test header", 
        "description": "Test description", 
        "type": {
            "id": 2, 
            "name": "Questions"
        }
        ...
    }, 
}

The 'data' is serialised topic or comment with the same structure like in our API. API introduction.

4. Response to webhook

You should send http response code 200. If our server will receive the other response code the webhook post will be repeated in 5 minutes. Our server waiting for 10 seconds for correct response. Best practice is to save response on your side in local queue and do immediate response to the our server after that you can process it accordingly.

5. Authenticating webhook requests (optionally)

UserEcho signs webhook requests so you can verify that requests are generated by UserEcho. If your application exposes sensitive data, you may want to be sure the requests are coming from UserEcho. This isn't required, but offers an additional layer of verification.

Verifying Request Signatures
UserEcho includes an additional HTTP header with webhook POST requests, X-UE-Signature (HTTP_X_UE_SIGNATURE), which will contain the signature for the request. To verify a webhook request, generate a signature using your key and compare that to the signature from the header.

Generate a signature:
Hash 'POST' string with HMAC-SHA1, using your key to generate a hexadecimal signature. Then compare it with the signature from the header.

You can get your key under Setup->Integration->Website->Webhooks section in the settings.

PYTHON example:

def get_signature(key, text):    import hmac
    import hashlib
    return hmac.new(str(key),msg=bytearray(text, 'utf-8'), digestmod=hashlib.sha256).hexdigest()

Leave questions and ideas for improving the functional of webhooks here:
http://feedback.userecho.com/topic/315761-webhook-for-custom-integrations/