SkillKit.Tools.Webhook (SkillKit v0.1.0)

Copy Markdown View Source

Kit that lets agents register webhook endpoints via skill activation.

Host wiring

SkillKit.start_agent("agents/support",
  tools: [{SkillKit.Tools.Shell, []}],
  skills: [
    {SkillKit.Tools.Webhook,
      github:  [secret_key: "GITHUB_WEBHOOK_SECRET"],
      stripe:  [secret_key: "STRIPE_WEBHOOK_SECRET", max_skew: 600],
      slack:   [secret_key: "SLACK_WEBHOOK_SECRET"],
      allow_unsigned: true}
  ])

Each configured provider binds its signing secret to the corresponding register skill. allow_unsigned: true additionally loads the webhook:unsigned skill for ad-hoc endpoints protected only by URL secrecy.

Skill surface

Always loaded (vendor register + management):

  • webhook:github, webhook:stripe, webhook:slack — signed vendor skills. Each stores the webhook with its verifier module pre-bound. If the host did not configure a vendor's secret, registration still succeeds (the LLM sees no error) but the resulting webhook's secret_key is nil; at on-hit time the verifier returns :misconfigured and the Plug responds 500. This design prevents the LLM from drifting to the unsigned skill as a fallback when a signed vendor appears unavailable.

  • webhook:update, webhook:unregister, webhook:list — vendor- agnostic management. Update is prompt-only; to rotate a verifier secret, unregister + re-register.

Opt-in:

  • webhook:unsigned — loaded only when allow_unsigned: true. The SKILL.md calls out when NOT to use it.

Runtime

When a register skill is activated, its metadata (verifier_module, secret_key, max_skew, supervisor) flows into the tool's ToolExecution.context. The register op reads those directly — it does NOT accept a verifier field from the LLM's tool input. The LLM has no capability to choose credential names or verifier modules.

Summary

Functions

Returns the agent definition from AGENT.md, or nil if not present.

Tool input schema. Override to declare parameters; defaults to an empty object. Called from the generated definition/0.

Functions

agent_definition()

Returns the agent definition from AGENT.md, or nil if not present.

input_schema()

Tool input schema. Override to declare parameters; defaults to an empty object. Called from the generated definition/0.