Webhooks¶

Webhooks let the outside world reach your agents. There are two directions to think about:

Inbound provider events — a service you've connected (like GitHub) calls Kwirker when something happens, and your agent reacts.
Skill webhooks — you expose one of your skills at a URL so your own systems can trigger it.

Both share the same path: a request arrives, we verify it's genuine, it passes through our guardrails, and only then does it reach your agent.

Inbound provider events¶

When you connect an integration that emits events, the platform creates a dedicated webhook URL and a signing secret for it. You register that URL with the provider.

Verifying signatures¶

Every provider request is signed, and we verify the signature before doing anything with the payload — using a constant-time comparison so a bad signature is rejected outright. For example, GitHub deliveries are checked against the X-Hub-Signature-256 header. If verification fails, the event is dropped.

No duplicates¶

Providers sometimes resend an event. We deduplicate on the provider's unique delivery ID, so a redelivery is acknowledged but never processed twice. Your agent sees each real event exactly once.

Rotating the secret¶

You can rotate a webhook's signing secret at any time from the integration's settings. Rotation is an admin action — update the secret on the provider side to match.

Skill webhooks¶

You can expose a skill at its own public URL so your systems can call it directly. Skill webhooks use a bearer token rather than a provider signature:

POST https://<your-skill-webhook-url>
Authorization: Bearer <skill-webhook-token>
Content-Type: application/json

{ "your": "payload" }

The token is verified with a constant-time check on every request. Calls that present a valid token are accepted (accepted); everything else is rejected (rejected). Either way, the call is logged — caller, time, and outcome — so you have a complete record.

What happens after a request is accepted¶

flowchart LR
    A[Incoming request] --> B{Verify signature / token}
    B -- invalid --> X[Rejected]
    B -- valid --> C[Guardrails]
    C --> D[Delivered to your agent]

Verification and guardrails always run first. A valid event is queued for your agent and processed reliably, even if your browser is closed.

Retries and replays¶

If your endpoint is the receiver (an inbound provider event), providers handle their own retries — if they don't get an acknowledgement, they resend, and our deduplication keeps that safe.

Testing¶

The most reliable way to test is to trigger a real event from the connected provider, or to POST to your skill webhook with its bearer token. Watch the conversation or the skill's invocation history to confirm your agent reacted.