diff --git a/_docs/incoming-webhooks.md b/_docs/incoming-webhooks.md index 3802c0b..9eb9435 100644 --- a/_docs/incoming-webhooks.md +++ b/_docs/incoming-webhooks.md @@ -1,106 +1,124 @@ --- title: "Incoming Webhooks" permalink: /docs/incoming-webhooks/ -excerpt: "Incoming Webhooks is a way to send posts from external sources into talkspirit." -modified: 2016-05-23 +excerpt: "Incoming Webhooks allow you to send posts from external sources into talkspirit." +modified: 2025-02-28 --- -Incoming Webhooks is a way to send posts from external sources into talkspirit -through a secret URL. The webhooks can be send to groups or users. Basically you -just have to send a simple HTTP requests with a JSON payload in UTF-8. +# Incoming Webhooks -Start by [setting up an incoming webhook integration][create-incoming-webhook] -in your talkspirit team, grab the token and start to send posts. +Incoming Webhooks enable you to send posts from external sources into talkspirit using a secret URL. You can send webhooks to groups or individual users by making a simple HTTP request with a JSON payload in UTF-8. -## Sending posts +To get started, [set up an incoming webhook integration][create-incoming-webhook] in your talkspirit team, obtain the token, and start sending posts. -You'll learn how to post a message like this: +## Sending Posts + +You can post messages using an incoming webhook. Here’s an example of a message sent via a webhook: ![](/img/docs/post-through-incoming-webhook3.png){: .align-center} -For this message your JSON payload needs to define these properties: +### JSON Payload Format + +To create a post, your JSON payload should include the following properties: - { - "title": "First post through Incoming Webhook", - "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", - "url": "https://www.talkspirit.com/", - "contact": { - "display_name": "Incoming Webhook bot", - "url": "https://www.talkspirit.com/", - "icon": "https://talkspirit.github.io/img/talkspirit-bot-avatar.png" - } - } +```json +{ + "title": "First post through Incoming Webhook", + "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", + "url": "https://www.talkspirit.com/", + "contact": { + "display_name": "Incoming Webhook bot", + "url": "https://www.talkspirit.com/", + "icon": "https://talkspirit.github.io/img/talkspirit-bot-avatar.png" + } +} +``` -The illustration bellow shows you where the payload properties are placed in the post: +The illustration below shows where these payload properties appear in the post:
-### CURL example - -Incoming Webhooks are in JSON format so you need to set the `Content-type` HTTP -header to `application/json`. - -You can easily test the Incoming Webhooks through the command line bellow. You -just need to copy/paste it and change the token (XXX...) by yours. - - curl -X POST -H 'Content-type: application/json' --data \ - '{ - "title": "First post through Incoming Webhook", - "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", - "url": "https://www.talkspirit.com/", - "contact": { - "display_name": "Incoming Webhook bot", - "url": "https://www.talkspirit.com/", - "icon": "https://talkspirit.github.io/img/talkspirit-bot-avatar.png" - } - }' https://webhook.talkspirit.com/v1/incoming/XXXXXXXXXXXXXXXXXXXXXXXX - -## Threaded posts - -talkspirit supports threads, so you can send many webhooks on the same post. The following -webhooks are added as comments of the initial post. - -To handle threaded messages you just have to define an identifier and set it in the payload in -the field `thread_id`. You can for example set the today's date or any unique identifier you want. - -Example: - - curl -X POST -H 'Content-type: application/json' --data \ - '{ - "title": "First post through Incoming Webhook", - "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", - "url": "https://www.talkspirit.com/", - "thread_id": "2016-09-16", - "contact": { - "display_name": "Incoming Webhook bot", - "url": "https://www.talkspirit.com/", - "icon": "https://talkspirit.github.io/img/talkspirit-bot-avatar.png" - } - }' https://webhook.talkspirit.com/v1/incoming/XXXXXXXXXXXXXXXXXXXXXXXX - - curl -X POST -H 'Content-type: application/json' --data \ - '{ - "content": "Lorem Ipsum is simply dummy text of the printing and typesetting industry.", - "thread_id": "2016-09-16", - "contact": { - "display_name": "Incoming Webhook bot", - "url": "https://www.talkspirit.com/", - "icon": "https://talkspirit.github.io/img/talkspirit-bot-avatar.png" - } - }' https://webhook.talkspirit.com/v1/incoming/XXXXXXXXXXXXXXXXXXXXXXXX - - -The result: +## Sending a Webhook Using cURL + +Since incoming webhooks use JSON, set the `Content-Type` HTTP header to `application/json`. + +You can test the webhook using the command below. Replace `XXXXXXXXXXXXXXXXXXXXXXXX` with your actual webhook token: + +```sh +curl -X POST -H 'Content-Type: application/json' --data ' +{ + "title": "First post through Incoming Webhook", + "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", + "url": "https://www.talkspirit.com/", + "contact": { + "display_name": "Incoming Webhook bot", + "url": "https://www.talkspirit.com/", + "icon": "https://talkspirit.github.io/img/talkspirit-bot-avatar.png" + } +}' https://webhook.talkspirit.com/v1/incoming/XXXXXXXXXXXXXXXXXXXXXXXX +``` + +### Debugging Your Webhooks + +To test and debug your webhook requests before sending them to talkspirit, you can use tools like: + +| Tool | Description | +|------|------------| +| [Beeceptor](https://beeceptor.com/) | Create a mock HTTP endpoint to inspect and debug webhook requests. | +| [Webhook.site](https://webhook.site/) | Monitor incoming HTTP requests and see detailed request logs. | + +## Threaded Posts + +talkspirit supports threads, allowing you to send multiple webhooks that appear as comments on an initial post. To achieve this, include a `thread_id` field in your payload. This can be any unique identifier, such as a timestamp or a custom string. + +### Example: Sending a Threaded Message + +#### Initial Post + +```sh +curl -X POST -H 'Content-Type: application/json' --data ' +{ + "title": "First post through Incoming Webhook", + "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", + "url": "https://www.talkspirit.com/", + "thread_id": "2025-02-28", + "contact": { + "display_name": "Incoming Webhook bot", + "url": "https://www.talkspirit.com/", + "icon": "https://talkspirit.github.io/img/talkspirit-bot-avatar.png" + } +}' https://webhook.talkspirit.com/v1/incoming/XXXXXXXXXXXXXXXXXXXXXXXX +``` + +#### Reply to the Thread + +```sh +curl -X POST -H 'Content-Type: application/json' --data ' +{ + "content": "This is a reply to the initial post.", + "thread_id": "2025-02-28", + "contact": { + "display_name": "Incoming Webhook bot", + "url": "https://www.talkspirit.com/", + "icon": "https://talkspirit.github.io/img/talkspirit-bot-avatar.png" + } +}' https://webhook.talkspirit.com/v1/incoming/XXXXXXXXXXXXXXXXXXXXXXXX +``` + +### Expected Result ![](/img/docs/post-through-incoming-webhook4.png){: .align-center} +--- + +By following these steps, you can integrate external sources with talkspirit using incoming webhooks. [create-incoming-webhook]: /docs/create-incoming-webhook/