Send data with a webhook
Create a webhook source, send it JSON from your own tools with curl or a signed request, add files by hand, and read every response.
A webhook source gives you a URL that any tool or script can POST JSON to, so Gurusup learns from tools that have no connector. This page is for the admin who creates the source and the developer who sends the data. Admins only. There is nothing to approve: the URL itself is the access.
At a glance
| Topic | Details |
|---|---|
| Who can connect | Admins create the source. Anyone with the URL can send to it. |
| What you need | A tool or script that can send a POST request |
| What Gurusup reads | Any JSON object you send, and files an admin adds by hand |
| How changes arrive | Whenever your tool sends a request |
| Past content | Send it yourself, or add files with Add data by hand. No Import history. |
| Knowledge access | Default access, Restricted or Private, chosen when you create it and editable later from Sources. See Who can read it. |
Before you start
- Decide who should read this source in Gurusup. You can change its access later from Sources, under Knowledge access.
- Decide whether the sender will sign requests. If so, pick a signing secret now: you cannot change it or read it back later.
Create a webhook source
Open the form
In the sidebar, open Sources, then Catalog, and click Add webhook source. The Add webhook source dialog opens.
Fill in the fields
- App name: the source's name. It also becomes part of the URL. See Name rules.
- Signing secret (optional): see Sign requests.
- Knowledge access: Default access, Restricted or Private. Gurusup says "Gurusup applies this from the first file it reads."
Create it and copy the URL
Click Create (it stays off until you type a name). Gurusup says "[name] connected. Send content to get started." and shows Send content to the name, with the Webhook URL. Click Copy, then Done.
Gurusup shows the complete URL only once, when you create it. It holds the access token, so treat it like a password and paste it straight into your tool. If you lose it, generate a new one.
Name rules
| Rule | Detail |
|---|---|
| Length | Up to 240 characters |
| In the URL | Lowercase. Letters a to z and numbers stay, every run of other characters becomes one hyphen, cut at 80 characters. "CRM events (EU)" becomes crm-events-eu. |
| Must contain | At least one letter or number |
| Signing secret | Between 1 and 2000 characters, if you set one |
What Gurusup reads
Gurusup reads each JSON object as text and learns from it with your other sources. Say a "Support escalations" webhook receives an event for each escalated ticket. Ask "Why is the Acme renewal at risk?" and Gurusup joins those events with the Slack thread about the outage and the deal in HubSpot, and cites the pages of its memory it drew from. See Sources and citations.
What the payload can be
| Field or shape | What Gurusup does |
|---|---|
| Any JSON object, any keys, any nesting | Reads the whole object as text |
| A JSON array, a string or a number | Rejects it. Wrap it in an object, for example {"items":[...]}. |
event, or type if there is no event (optional) | Stored as the request's label. With neither, the label is raw.received. |
| An id (optional) | The first non-empty value of data.uuid, data.id, data.resource_id, uuid, id, resource_id, stored as the request's id so you can trace it |
Each item on Ingest gets a title from its content. Gurusup uses the first match and cuts it at 300 characters. With no match, Ingest shows "Untitled item". Items stored before this change keep the title they had.
| Order | Where Gurusup looks |
|---|---|
| 1 | issue.fields.summary, shown as issue.key · summary, or the summary alone when there is no key |
| 2 | summary, then subject, at the top level |
| 3 | title, name, summary or subject inside issue, ticket, task, item, object, record or data, in that order |
| 4 | data.title, data.name, then title or name at the top level |
How changes arrive
Every request you send is stored and learned. There is no separate connect step.
Send data
curl -X POST "https://YOUR-WEBHOOK-URL" \
-H "Content-Type: application/json" \
-d '{"event":"ticket.escalated","id":"TCK-1042","customer":"Acme","summary":"Renewal at risk after the second outage"}'
Replace https://YOUR-WEBHOOK-URL with your Webhook URL. A successful request answers HTTP 202:
{
"status": "queued",
"event": "ticket.escalated",
"resource_id": "TCK-1042",
"source_id": "src_..."
}
"queued" means stored, not learned yet: follow it on Follow ingestion.
Test a request
Add ?test=true to the URL. Gurusup checks the URL, the signature if you set a secret, and that the body is a JSON object, then answers 202 with "status": "verified". It stores nothing and uses no usage. Sign test requests too. While ingestion is paused or Demo Mode is on, they get the "ignored" answer.
curl -X POST "https://YOUR-WEBHOOK-URL?test=true" \
-H "Content-Type: application/json" \
-d '{"event":"test"}'
Sign requests
If you set a Signing secret, sign the raw request body with HMAC-SHA256 using that secret, and send sha256= followed by the hex digest in the X-Webhook-Signature header. Sign exactly the bytes you send.
BODY='{"event":"ticket.escalated","id":"TCK-1042","customer":"Acme"}'
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" | sed 's/^.* //')
curl -X POST "https://YOUR-WEBHOOK-URL" \
-H "Content-Type: application/json" \
-H "X-Webhook-Signature: sha256=$SIGNATURE" \
-d "$BODY"
Without a secret, requests are not checked for a signature.
Retries and repeated requests
If your sender repeats a request with exactly the same JSON body, for example because the answer was lost, Gurusup keeps one copy and learns it once. It does not use usage twice. The order of the keys does not matter. A request whose body differs in any way, such as a second edit of the same ticket, is accepted as its own item. Both get the 202 answer. Retry only on an error or no answer.
Add data by hand
An admin can add files to a webhook source without writing code.
Open Add data
On Sources, open the webhook source's page. Under Content, next to "Incoming content" ("Send content from your tools or upload it here."), click Add data. The Send files to dialog opens.
Choose files
Drop in or choose files, including Word (.docx), PowerPoint (.pptx) and Excel (.xlsx) files. The line under the drop area reads "Documents, spreadsheets, presentations, PDFs, text files and wiki exports, or a ZIP of them." See supported files lists every extension, and Limits and messages links to these limits. Gurusup shows the estimated usage and, for each file it cannot read, why, with the file name.
Ingest
Click Ingest. It sends right away, with no confirm step. Gurusup says how many documents it sent, for example "Sent 3 documents." If it skipped a file, it names it: "a.key wasn't sent: Gurusup can't read that kind of file. Save it as a PDF, Word or Excel file and send it again." For several files it reads "2 files weren't sent because Gurusup can't read them" followed by the first names.
| Add data (webhook source) | Upload files | |
|---|---|---|
| Formats | docx, pptx, xlsx, html, htm, md, txt, csv, json, pdf, org, adoc, canvas, tid, textpack, xml (MediaWiki), enex (Evernote), ZIP or TAR.GZ | Same formats |
| Size | 25 MiB combined, checked in the app before anything is sent | 256 MiB per file |
| File count | Up to 1,000 files | See Upload content |
| Confirm step | None. Ingest sends immediately. | Estimate and confirm |
| Ends up in | The webhook source you chose | The Local Uploads source |
Failures start with "Could not send files."
| Message | What to do |
|---|---|
| "No files selected. Choose documents or an archive to send." | Add a file first. |
| "Upload exceeds the 25 MiB (26,214,400 bytes) combined limit. Choose fewer or smaller files." | Send fewer or smaller files, or use Upload files for big ones. |
| "At most 1000 files may be uploaded." | Split the upload. |
| "These files are larger than the upload limit. Upload fewer or smaller files." | Split the upload. |
| A message naming a file, such as "(file) needs a password to open. Upload a copy that opens without a password." | Fix that file and add it again. |
| "Gurusup couldn't accept these files right now. This is on our side. Try again in a few minutes, and contact support if it keeps failing." | Try again later. |
Files are read as in Upload files, with the same formats and the same messages for a file Gurusup cannot read: see Refusals and fixes. How each export comes in is in Exports from other tools.
Who can read it
You choose Default access, Restricted or Private when you create a webhook. You can change its access later under Knowledge access on the webhook's page; it saves as soon as you change it. A webhook created in setup has Default access. Restricted lets only the people you pick read it. Private lets only you read it. Administrators are not included unless picked. See Restrict a source to specific people.
Check that it worked
Send a request
Send a request with curl. You get 202 and "status": "queued".
Find the row
On Sources, the webhook source has a row. Open it to see its page. Its Contribution rises once Gurusup has learned from the request.
Follow it
On Ingest, pick the webhook source in the filter. The request moves from Queued to Learning to Learned.
Regenerate the URL
If the URL leaks or you lost it, replace it. On Sources, open the webhook's page. Under Danger zone, open the menu on Regenerate webhook token, choose it and confirm. The row says "Replace the current webhook URL. Update the sending tool with the new URL before it can send data again." Gurusup shows the new URL under Content. In setup, click View sending instructions on the webhook, then Generate new URL. Gurusup asks "Replace the URL for [name]?"; click Replace URL.
Copy the new URL and update your tool. The old one stops working at once, with the 401 "This webhook URL isn't recognized." answer. The signing secret stays the same. To use a different secret, create a new source. A failure starts with "Could not regenerate token."
Remove a webhook source
On the webhook's page, under Danger zone, open the menu on Remove source, choose it and confirm. The URL stops working at once (401 "This webhook URL isn't recognized.") and what Gurusup learned stays. See Remove, disconnect and what stays.
When ingestion is paused
While ingestion is paused or Demo Mode is on, Add webhook source, Add data, Send JSON and Regenerate token are off, and requests get the 202 "ignored" answer. Remove source still works while ingestion is paused, but not in Demo Mode. Nothing sent meanwhile is stored. The setup panel still opens to show the sending instructions, with "Demo Mode is read-only. You can view your webhook instructions." or "Ingestion is paused. You can view your webhook instructions; changes will be available when ingestion resumes." See When ingestion is paused or Demo Mode is on.
If it does not work
Every response
Errors come back as JSON with the message in a detail field. Gurusup checks the URL, then the signature, then whether ingestion is paused, then the body.
| Status | Message or body | What it means and what to do |
|---|---|---|
| 202 | "status": "queued" | Accepted. |
| 202 | "status": "verified" | A ?test=true request passed the checks. Nothing was stored. |
| 202 | "status": "ignored" with "reason": "ingestion_paused" or "reason": "demo_mode" | Nothing stored: ingestion is paused or Demo Mode is on. Do not retry. Contact support. |
| 400 | "The request body couldn't be read as JSON. Send a JSON object." | The body is not valid JSON. |
| 400 | "Webhook payload must be a JSON object" | Valid JSON, but not an object, for example an array. |
| 401 | "This webhook URL isn't recognized. Use the current URL from the webhook source." | The URL is wrong, was regenerated, or its source was removed. |
| 401 | "The webhook signature doesn't match. Send X-Webhook-Signature as sha256=<hex HMAC-SHA256 of the raw body, keyed with the signing secret>." | Missing or wrong signature. Sign the exact body bytes with the source's secret. |
| 404 | "Webhook source not found" | The name part of the URL is not valid. Use the URL you copied. |
| 503 | "We couldn't finish this because of a problem on our side. Your connections and data are safe. Try again in a few minutes, and contact support if it keeps failing." | Retry later. |
| 503 | "Webhooks can't be received right now because of a problem on our side. Contact support and we'll sort it out." | Retry later, then contact support. |
Retry on 503 and on network errors. Do not retry on 400, 401 or 404 until you fix the cause.
If creating fails
The red message starts with "Could not create webhook source."
| Reason | What to do |
|---|---|
| "Webhook source name must contain letters or numbers." | Use at least one letter or number. |
| "Signing secret must contain between 1 and 2000 characters." | Shorten the secret, or leave it empty. |
| "Only organization admins can manage integrations." | Ask an admin. |
| "Ingestion is paused for this organization. Ask your organization admin to resume ingestion before adding content." | Contact support. |
| "Demo Mode prevents changing external sources. Ask your organization admin to turn off Demo Mode to continue." | Contact support. |
| "Webhook sources can't be created right now because of a problem on our side. Nothing was created. Contact support and we'll sort it out." | Contact support. |
| "We couldn't save this webhook source because of a problem on our side. Nothing was created. Try again in a few minutes, and contact support if it keeps failing." | Try again in a few minutes. |
| "We couldn't save the signing secret because of a problem on our side. Nothing was created. Try again in a few minutes, and contact support if it keeps failing." | Try again in a few minutes. |