ConnectorsWebhook

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

TopicDetails
Who can connectAdmins create the source. Anyone with the URL can send to it.
What you needA tool or script that can send a POST request
What Gurusup readsAny JSON object you send, and files an admin adds by hand
How changes arriveWhenever your tool sends a request
Past contentSend it yourself, or add files with Add data by hand. No Import history.
Knowledge accessDefault 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

RuleDetail
LengthUp to 240 characters
In the URLLowercase. 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 containAt least one letter or number
Signing secretBetween 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 shapeWhat Gurusup does
Any JSON object, any keys, any nestingReads the whole object as text
A JSON array, a string or a numberRejects 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.

OrderWhere Gurusup looks
1issue.fields.summary, shown as issue.key · summary, or the summary alone when there is no key
2summary, then subject, at the top level
3title, name, summary or subject inside issue, ticket, task, item, object, record or data, in that order
4data.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
Formatsdocx, pptx, xlsx, html, htm, md, txt, csv, json, pdf, org, adoc, canvas, tid, textpack, xml (MediaWiki), enex (Evernote), ZIP or TAR.GZSame formats
Size25 MiB combined, checked in the app before anything is sent256 MiB per file
File countUp to 1,000 filesSee Upload content
Confirm stepNone. Ingest sends immediately.Estimate and confirm
Ends up inThe webhook source you choseThe Local Uploads source

Failures start with "Could not send files."

MessageWhat 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.

StatusMessage or bodyWhat 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."

ReasonWhat 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.