Incoming Webhooks

Incoming webhooks let any system that can send an HTTP POST notify Junto when something happens -- a meeting ends, a monitoring platform raises an alert, a form is submitted. Every call is recorded as a delivery. You name the recurring event shapes you care about as triggers, then attach runbooks to a trigger so a matching delivery starts a run automatically.

How It Works

1. Create an endpoint in Junto. Each endpoint gets its own URL and verification method.
2. Paste the URL into the sending system and send a test event. It appears in the Deliveries tab within a few seconds.
3. Make a trigger from a delivery by choosing which payload fields identify that kind of event.
4. Attach a runbook to the trigger from the runbook's page. Future matching deliveries start a run.

Only users with the Admin or Owner role can manage endpoints, triggers, and runbook attachments.

Creating an Endpoint

1. Go to Settings > Integrations and open Incoming webhooks in the Internal section.
2. Click Add endpoint and fill in:

Field	Description
Name	A label for the sending system (e.g., "Granola meetings").
Verification	How Junto confirms the call really came from the sender. See below.
Header name	For HMAC and shared-token verification, the header the sender puts the signature or token in (e.g., X-Signature, X-Api-Key).
Signing secret / Token	The secret shared with the sender. It is stored encrypted and never shown again. When editing, leave it blank to keep the saved value.

3. Click Create endpoint.

The endpoint panel shows the URL with a Copy URL button, the verification type, when the last delivery arrived, and whether the endpoint is Active or Paused. You can Edit or Delete an endpoint at any time. Deleting stops the URL immediately and removes its deliveries and triggers, so turn the webhook off in the sending system too.

Verification Methods

Method	When to use it
Standard Webhooks (default)	The sender follows the Standard Webhooks spec (Svix-based senders and many SaaS products). Junto checks the signature and rejects timestamps more than 5 minutes off.
HMAC-SHA256 header	The sender signs the raw request body with HMAC-SHA256 and sends the result in a header. Hex or base64 encoding is accepted, with or without a sha256= prefix.
Shared token header	The sender puts a fixed token in a header. A Bearer prefix is accepted.
No verification	Only the URL itself is secret. Use this for senders that cannot sign requests.

Deliveries

The Deliveries tab lists every call to the endpoint, newest first, with Received, Event, Signature, Trigger, and Payload columns. The first page refreshes automatically.

• Signature shows Verified, Unsigned, or Rejected. Rejected deliveries never start a run.
• Trigger shows which trigger matched (or None) and how many runs started.
• A Repeat badge marks a delivery whose event ID was seen before. Repeats never start a second run.

Click a delivery to see the full record: the signature result and reason, event ID, size, the runs it started (each linked to its execution, or the reason it was skipped or failed), the pretty-printed JSON payload, and the request headers. Authorization headers and the shared-token header are redacted.

Receiver Limits

• Requests are POST (or PUT) with a JSON body. Non-JSON bodies are recorded but cannot match a trigger.
• Payloads larger than 256 KB are rejected.
• Each endpoint accepts up to 60 deliveries per minute. Beyond that, the sender receives a 429 with a Retry-After header and nothing is recorded.
• Deliveries are kept for 30 days.
• Junto does not retry or replay inbound deliveries. If Junto cannot store a delivery it answers 503, so well-behaved senders retry on their own.

Example

A shared-token endpoint can be tested with a single request:

curl -X POST "<endpoint URL copied from Junto>" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <the token you entered>" \
  -d '{"event_type":"meeting.finished","meeting":{"id":"123","title":"Weekly sync"}}'

A successful call returns 202 with {"status":"received"}.

Triggers

A trigger names one kind of event so you can attach runbooks to it.

1. Open a delivery that represents the event and click Make trigger. (The button is disabled for rejected or non-JSON deliveries.)
2. Give it a Trigger name (unique per endpoint, e.g., "Meeting finished").
3. Under Match deliveries where, tick the payload fields that identify this event. Type-like fields such as event_type, type, or action are pre-selected; IDs and timestamps are not. You can select up to 10 fields.
4. Watch the live preview -- "Matches X of the last Y deliveries" -- and adjust until it matches only the events you want.
5. Click Create trigger.

A delivery matches a trigger when every selected field equals the saved value. If several triggers could match, the first one wins. Recent deliveries that match are labelled retroactively.

The Triggers tab lists each trigger's conditions and the runbooks it starts. Deleting a trigger keeps past deliveries but removes the label.

Starting Runbooks from a Trigger

1. Open a published runbook and click Webhooks (next to Run now and Schedule).
2. Click Attach trigger and choose:
   • Trigger -- grouped by endpoint.
   • Company -- required if the runbook files a completion ticket; otherwise optional. Leave it empty to let the run work across companies.
   • Board / Queue -- shown when the runbook files a ticket, labelled for your PSA.
   • Fill runbook inputs from the webhook -- map each runbook input to a payload field, or leave it unfilled.
3. Click Attach trigger.

Each attachment shows the endpoint and trigger, the company (or All companies), who the run acts as, the input mapping, an Active switch to pause it, and Detach.

How Webhook Runs Behave

• Runs act as the person who attached the trigger, with that person's connections and permissions. If that user is removed or no longer an Admin, runs are skipped until someone else re-attaches the trigger.
• The run receives the mapped input values and the payload as data, along with the trigger name, endpoint name, time received, and company. Payload contents are never treated as instructions to the agent.
• Runs follow the runbook's normal approval settings. See Reviews & Approvals.
• Limits: one run per event per attachment, two runs of the same attachment in flight at a time, and 20 runs per endpoint per hour. Runs beyond these limits are recorded on the delivery as skipped with the reason.
• Webhook-started runs appear on the runbook's Runs page with a Webhook badge, and each delivery links to the runs it started.

Troubleshooting

• Deliveries show Rejected -- Open the delivery to see the reason: a signature that did not match the secret, a timestamp more than 5 minutes off, missing signature headers, or a wrong token. Confirm the sender uses the same secret and header name you entered.
• Delivery arrived but no trigger matched -- Compare the payload fields against the trigger's conditions. The sender may have changed its payload shape; make a new trigger from a recent delivery.
• Trigger matched but no run started -- The delivery detail shows why: the runbook is not published, the attachment is paused, the attaching user lost Admin access, or a run limit was hit. Repeats never start a second run.
• Sender reports 429 -- The endpoint exceeded 60 deliveries per minute. Have the sender batch or slow down.
• Sender reports 404 -- The endpoint is paused or was deleted.