Webhook

Repsona Webhook allows you to receive event notifications and trigger actions automatically. It sends events such as task or note updates, comment additions, status changes, etc. to a specified URL (HTTP request). Can be used for integration with other services and systems.

Steps to receive a webhook

You can initiate a webhook in the following steps

• Create a Webhook endpoint.
• Process (implement) the request from Repsona
• Configure the Webhook endpoint with Repsona
• Test the Webhook endpoint
• Verify the Webhook signature (recommended)

Create a Webhook endpoint

Create an HTTP endpoint that can accept unauthenticated Webhook requests using the POST method.

Process requests from Repsona (implementation)

The endpoint must be configured to read an Event (Event) object of the type of event notification it receives; Repsona sends the event to the Webhook endpoint as part of a POST request with a JSON payload. The event should be parsed and return a 2xx status code. The model, modelId and action can be analysed to determine what to do.

Example payload.

{
  "type": "Task.update",
  "event": {
    "id": 20004,
    "createdAt": 1673021684000,
    "task": {
      "id": 2,
      "status": {
        "id": 1,
        "name": "Todo",
        "isClosed": false,
        "space": 1,
        "project": 1
      }
    },
    "user": {
      "id": 1,
      "name": "Reon",
      "fullName": "Reon Walls",
      "avatarUrl": "/dummy/avatar1.png"
    },
    "project": {
      "id": 1,
      "name": "elephant-website",
      "fullName": "Elephant website development project"
    }
  }
}

Configure the Webhook endpoint to Repsona.

From the Project Settings > Webhooks page, set the webhook endpoint URL and the event type to be notified The webhook endpoint URL must be a publicly accessible HTTPS URL.

Testing Webhook endpoints.

From the Project Settings > Webhooks page, test data can be sent to the registered URL. You can check the contents and results of the transmission in the transmission history list.

Checking the Webhook signature (recommended)

Send events including a signature in the Repsona-Signature header. This allows you to verify that the event was sent by Repsona and not by a third party. To verify the signature, the signature secret must have been previously obtained from the webhook configuration.

The Repsona-Signature header in the event contains a timestamp and a signature. The timestamp is preceded by t= and the signature by s=.

Repsona-Signature: t=1674544389,s=768b05feb76b244902ab3a4eca119abb98e530ccbc3f2c48e18a7ed3a1cea0ab

Extracting timestamps and signatures from headers

To get a list of elements, split the header using the , character as a delimiter. Then, separate each element using the = character as a delimiter to get the prefix-value pairs. The value of the t prefix corresponds to the timestamp, while the s corresponds to the signature.

Preparing the signed_payload string

A signed_payload string is created by concatenating the following.

• Timestamp (as a string)
• Character .
• The actual JSON payload (request body)

Determine the expected signature

Calculate the HMAC using the SHA256 hash function. Use the endpoint's signature secret as key and the signed_payload string as message.

Comparing signatures

Compares the signature in the header with the expected signature. If a match is found, the difference between the current timestamp and the received timestamp is calculated to determine if the difference is acceptable.