> For the complete documentation index, see [llms.txt](https://notara.gitbook.io/notara-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://notara.gitbook.io/notara-docs/automations/webhooks.md). # Webhooks Incoming webhooks let external systems trigger the Notara agent in real time. When an event happens in GitHub, Stripe, your own app, or any other system, it can POST to a Notara webhook endpoint and the agent responds in the configured Slack channel. ## How It Works 1. You create a webhook in the Notara dashboard and get a unique endpoint URL. 2. You configure the external system to POST JSON to that URL when an event occurs. 3. Notara receives the payload, injects it into the agent's context as structured data. 4. The agent processes it according to the webhook's configured prompt and posts a response to the configured Slack channel. The whole flow typically takes 5–15 seconds from event to Slack message. ## Creating a Webhook 1. Go to **Automations → Webhooks** in the dashboard. 2. Click **+ New Webhook**. 3. Fill in the configuration: | Field | Description | | ----------- | ------------------------------------------------------- | | **Name** | Human-readable label (e.g., "GitHub PR Merged") | | **Channel** | Slack channel where the agent's response is posted | | **Prompt** | Instructions for how the agent should process the event | | **Active** | Enable immediately or save as draft | 4. Click **Save**. You'll see the generated endpoint URL. Your endpoint URL looks like: ``` https://app.notara.ai/hooks/wh_abc123def456 ``` This token is unique to your webhook and is effectively a secret — anyone with it can trigger the webhook. Treat it like an API key. ## The Payload POST to the webhook endpoint with a JSON body: ```bash curl -X POST https://app.notara.ai/hooks/wh_abc123def456 \ -H "Content-Type: application/json" \ -d '{ "event": "pr.merged", "pr": { "number": 142, "title": "Fix race condition in auth flow", "author": "max", "merged_by": "amir", "url": "https://github.com/acme/api/pull/142" } }' ``` The entire JSON body is injected into the agent's context. The agent can reference any field in the payload when forming its response. ## Writing a Good Webhook Prompt The prompt tells the agent what to do with the incoming event. It should explain what kind of events this webhook receives and what output is expected. **Example: GitHub PR merged** ``` A GitHub pull request was just merged. The event payload contains the PR details. Summarize what was merged in 2-3 sentences, note the author and any linked issues if present, and suggest any follow-up actions (e.g., if the title mentions a bug fix, check if there's a related Linear issue to close). Keep the message under 200 words. ``` **Example: Stripe new customer** ``` A new Stripe customer has been created. The event payload contains the customer object. Post a brief welcome notification with: customer email, plan name if available, and the customer ID. Keep it under 100 words. Format: "New customer: [email] | Plan: [plan] | ID: [id]" ``` **Example: Custom app alert** ``` An error alert was triggered by the production API. The payload contains error details. Summarize the error, severity, affected endpoint, and estimated user impact. If the error code matches a known pattern in our runbook library, reference the relevant procedure. ``` ## Real-World Examples ### GitHub → Notara via GitHub Actions ```yaml # .github/workflows/notify-notara.yml on: pull_request: types: [closed] jobs: notify: if: github.event.pull_request.merged == true runs-on: ubuntu-latest steps: - name: Notify Notara run: | curl -X POST ${{ secrets.NOTARA_WEBHOOK_URL }} \ -H "Content-Type: application/json" \ -d '{ "event": "pr.merged", "pr": { "number": ${{ github.event.pull_request.number }}, "title": "${{ github.event.pull_request.title }}", "author": "${{ github.event.pull_request.user.login }}", "url": "${{ github.event.pull_request.html_url }}" } }' ``` ### Stripe → Notara via Stripe Webhooks 1. In your Stripe dashboard, go to **Developers → Webhooks → Add endpoint**. 2. Enter your Notara webhook URL. 3. Select the events to send (e.g., `customer.subscription.created`, `payment_intent.succeeded`). 4. Stripe will POST the full event object to Notara when they fire. ### Your Own App → Notara Add a call to the Notara webhook wherever you want to trigger a notification: ```typescript // In your app's event handler await fetch(process.env.NOTARA_WEBHOOK_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ event: 'user.trial_expired', user: { email: user.email, plan: user.plan, daysSinceSignup: user.daysSinceSignup } }) }); ``` ## Security ### Keeping the URL Secret The webhook URL is a bearer token — anyone with it can trigger the webhook. Store it in your secrets manager (GitHub Secrets, Doppler, AWS Secrets Manager) rather than hardcoding it. To rotate the URL, delete the webhook and create a new one. Update the secret in any systems using the old URL. ### Payload Validation For high-security scenarios, you can validate that a payload came from the expected source by including a shared secret in a header and verifying it in your webhook prompt or via the HMAC verification option (available in the advanced webhook settings). ### Rate Limiting Each webhook endpoint is rate-limited to prevent abuse. If you expect high-volume events (e.g., many Stripe events per minute), contact to discuss higher limits. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://notara.gitbook.io/notara-docs/automations/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.