Skip to content

Update incoming-webhooks.md #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update incoming-webhooks.md #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 97 additions & 79 deletions _docs/incoming-webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:

<figure>
<img src="/img/docs/post-webhook.png" alt="">
<figcaption>
<ul>
<li>blue: contact properties</li>
<li>green: message properties</li>
<li><span style="color:blue">Blue</span>: Contact properties</li>
<li><span style="color:green">Green</span>: Message properties</li>
</ul>
</figcaption>
</figure>

### 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/