1. Learn
2. Webhooks

Webhooks

Webhooks allow you to build integrations that subscribe to certain events happening in the Weavy environment. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Essentially this means you need to set up endpoints on your server that can respond to the received data.

You can for example use webhooks to synchronize information between systems, create reports, send push notifications and more.

Creating webhooks

You can register and manage webhooks through the Webhooks API. Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.

Payload URL

The payload URL is the URL of the server that will receive the webhook POST requests. The payload will be delivered as JSON in the request body using the application/json content type.

Secret

Configuring a webhook secret allows you to ensure that POST requests sent to the payload URL are from your Weavy environment. When you set a secret, Weavy uses it to create a hash signature of the payload using the HMAC-SHA256 algorithm. This hash signature is included in the X-Weavy-Signature header in the webhook POST request.

Triggers

When configuring a webhook, you can choose which events will trigger the webhook and send you payloads. Each trigger corresponds to a certain set of actions that can happen in your Weavy environment. The list of triggers you can choose from are:

• comments
• conversations
• files
• messages
• notifications
• polls
• posts
• reactions

Example: Registering a webhook that will receive a detailed payload every time a reaction is added or removed.

curl {WEAVY-URL}/api/webhooks 
-H "Authorization: Bearer {API-KEY}" 
--json "{'payload_url': 'https://example.com/myapp/webhooks', 'triggers': ['reactions']}"

Payloads

All webhook payloads have common headers and properties describing the event that occurred. Additionally, they also contain properties unique to the specific event.

Delivery headers

Payloads that are delivered to your webhook's configured URL endpoint will contain several special HTTP headers:

• X-Weavy-Delivery – A GUID to identify the delivery.
• X-Weavy-Signature – This header is sent if the webhook is configured with a secret. This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the secret as the HMAC key.
• X-Weavy-Trigger – Name of the event that triggered the delivery.

Also the standard User-Agent header for the request will have the prefix WeavyBot/.

Common payload properties

The following common properties are included in all webhook payloads:

• id – Unique identifier for the event (shared with all deliveries for all webhooks that subscribe to this event).
• action – The type of activity that triggered the event.
• actor – The user that triggered the event.

Specific payload properties

The listing below describes specific payload properties for the different triggers. You will find that sensitive data such as message and notification text is always redacted from the payload. To access this data your server will need to make an additional roundtrip to the Weavy environment.

For instance, if you are subscribed to the notifications trigger you will get a delivery whenever a notification is created. To see the actual notification text your server has to call the get notification endpoint and authorize the request with an access_token for the notification recipient. Not ideal, we know, but it's all in the name of security and privacy.

Comments

• action – Can be one of comment_created, comment_updated, comment_deleted.
• comment - The comment itself.

Conversations

• action – Can only be conversation_marked which indicates that a conversation read marker was updated (read/unread).
• conversation - The conversation.
• marked_at - The current date and time (UTC) of the read marker (when the conversation was last read/unread).
• marked_id - Id of the last read message.

Files

• action – Can be one of file_created, file_updated, file_deleted.
• file - The file itself.

Messages

• action – Can be one of message_created, message_updated, message_deleted.
• message - The message itself.

Notifications

• action – Can be one of notification_created, notification_updated, notifications_marked.
• notification - The notification itself.

Polls

• action – Can be one of vote_added, vote_removed.
• poll - The poll where the vote was added/removed.
• option - The poll option the user voted for.

Posts

• action – Can be one of post_created, post_updated, post_deleted.
• post - The post itself.

Reactions

• action – Can be one of reaction_added, reaction_removed.
• entity - The entity that was reacted to.
• reaction - The emoji character that was used in the reaction.

Example delivery

The example below shows what a typical delivery request for the reaction_added event could look like:

POST https://example.com/myapp/webhooks HTTP/1.1
User-Agent: WeavyBot/1.0
X-Weavy-Delivery: 78c57235-a3f3-4c60-b694-2fdc2f6d515c
X-Weavy-Signature: sha256=31591413bc17fd8f32b697f20e97f8241a9cbd769e81c9f1eea3159706374f9d
X-Weavy-Trigger: reactions
Content-Type: application/json; charset=utf-8
Content-Length: 319

{
  "id": 11,
  "action": "reaction_added",  
  "actor": {
    "id": 51,
    "display_name": "John Doe",
    "email": "john.doe@example.com",
    "created_at": "2021-10-29T13:28:11.8433333Z"
  },  
  "entity": {
    "id": 233,
    "type": "message"
  },
  "reaction": "😍"    
}

Best practices

In the section below, we have outlined some best practices you should be following when deploying your webhooks to production.

Event subscription

By only subscribing to the specific triggers/events you plan on handling, you'll limit the load on the Weavy environment and the number of HTTP requests to your server.

Secure delivery

Webhook payloads may contain sensitive information and it's important that you secure the payloads sent from Weavy. There are several steps you can take to secure receipt of payloads delivered by Weavy:

1. Ensure that your receiving server is on an HTTPS connection.
2. Add the IP address of the Weavy environment to your server's allow list.
3. Provide a webhook secret and verify the calculated signature.

Depending on the programming language on your server, the code required to verify the signature may differ slightly, but the following pseudocode explains the basic steps.

var signature = "sha256=" + HMAC_SHA256(config["webhook_secret"], Request.Body);
if (signature != Request.Headers["X-Weavy-Signature"]) {
    return BadRequest();
}

Asynchronous processing

Weavy expects that your server respond within 10 seconds of receiving the webhook payload. If your service takes longer than that to complete, the connection will be terminated and the payload is lost.

Since it's impossible to predict how fast your service will complete, you should do all of "the real work" in a background job. Note that even with a background job running your server still needs to acknowledge that it received the payload by sending some sort of response within 10 seconds.

Use appropriate HTTP status codes

You should make use of proper HTTP status codes when responding to webhook deliveries. You can use codes like 200 or 202 to acknowledge receipt of payload. Reserve the 500 error code for catastrophic failures.

Check the trigger and action

There are multiple webhook triggers, and each trigger can have multiple actions. As Weavy's feature set grows, we will occasionally add new triggers or add new actions to existing triggers. Ensure that your application explicitly checks the trigger and action of any event before doing any webhook processing. The X-Weavy-Trigger request header can be used to know which trigger was fired so that processing can be handled appropriately. Similarly, the payload has a top-level action key that can be used to know which action was taken on the relevant object.

Troubleshooting

When developing a webhook integration it can be useful to view the webhook requests and payloads being sent (as well as the response from your server).

Each webhook keeps a list of recent deliveries which you can access through the management interface or the Webhooks API. The delivery contains information such as status (success/failure), when the delivery was attempted, the duration of the request etc. The delivery also includes the full HTTP Request and Response including headers and body if you want to see exactly what Weavy attempted to send to your server.

To help in troubleshooting webhook deliveries your server should always try to respond with clear and informative messages.