webhooks
/webhooks
Use when the developer wants their server told when a request is raised, replied to or closed, or when the assistant answers: Opem webhooks, verifyWebhook from @opem/node, the Opem-Signature header, the whsec_ secret, redelivery, or testing a webhook handler locally.
- Author
- agile-4 ↗
- Repository
- opem-agent-plugin ↗
- Licence
- MIT
- Last repository change
- 10.11.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/sign-test-delivery.mjs
What it does and when to use it
Use when the developer wants their server told when a request is raised, replied to or closed, or when the assistant answers: Opem webhooks, verifyWebhook from @opem/node, the Opem-Signature header, the whsec_ secret, redelivery, or testing a webhook handler locally.
Original author description
Use when the developer wants their server told when a request is raised, replied to or closed, or when the assistant answers: Opem webhooks, verifyWebhook from @opem/node, the Opem-Signature header, the whsec_ secret, redelivery, or testing a webhook handler locally.
How it works
- First: is Opem connected?
- Stop at the chosen step
- Before you start
- Steps
- Without the connection
- When verifying fails
- References
SKILL.md preview
---
name: webhooks
description: "Use when the developer wants their server told when a request is raised, replied to or closed, or when the assistant answers: Opem webhooks, verifyWebhook from @opem/node, the Opem-Signature header, the whsec_ secret, redelivery, or testing a webhook handler locally."
---
# Receive Opem's webhooks
Opem posts a signed JSON `POST` to the developer's endpoint for five events. The handler verifies the signature, deduplicates on the event id, answers `2xx` quickly and does the work after.
## First: is Opem connected?
Look for the Opem tools (`whoami`, `list_projects`). If the only Opem tool is `authenticate`, call it now and wait for the developer to sign in and consent; then call `whoami`. Only when the server cannot be connected, follow the dashboard path below.
## Stop at the chosen step
Do the steps the developer chose (their answers to the how-far questions the `onboard` and `install` skills ask, or what they asked for) and no further. When the next step would add a dependency, a file to the repository, a key, a workflow or a switch they did not ask for, name it as the next offer and stop. If nothing has been chosen yet, ask before the first such step.
## Before you start
- Webhooks come with Professional and Enterprise. On other plans the Webhooks tab is read-only and nothing is delivered.
- The endpoint must be `https://` on a public address: no localhost, no private networks. For local work, a tunnel (see [local-testing.md](references/local-testing.md)) or the offline signer below.
- The signing secret (`whsec_…`) is shown once, when the endpoint is made. It goes into the server's environment as `OPEM_WEBHOOK_SECRET`, never into code or a chat.
## Steps
0. **Make the endpoint** once its public https URL is known (a deployed host, or a tunnel from [local-testing.md](references/local-testing.md)). `create_webhook` with the URL and the events (optionally disabled) makes it and returns its `whsec_` secret once: write it to the environment file as `OPEM_WEBHOOK_SECRET` in the same step and never echo it. The tool needs the connection's `keys` permission (`whoami` lists it); without it the answer is `forbidden`, and the developer reconnects with `keys` ticked or uses the dashboard below.
1. **Write the handler** from [handler.md](references/handler.md): read the raw body as text, call `verifyWebhook({ body, headers, secret })`, which returns the typed event or throws on a bad signature or a delivery older than five minutes. In Express use `express.raw({ type: "application/json" })` on the route; a framework that parses JSON first changes the bytes that were signed.
2. **Deduplicate.** Keep the handled event ids; a delivery can arrive more than once, and a copy within five minutes verifies too. Return `204` early for one seen before.
3. **Answer fast, work after.** Opem waits ten seconds for a `2xx` and never follows redirects; queue anything slow.
4. **Branch on `event.type`.** The events, what `data` holds, the headers and the retry schedule are in [events.md](references/events.md).
5. **Test offline** with a signed sample delivery:
```sh
OPEM_WEBHOOK_SECRET=whsec_test node scripts/sign-test-delivery.mjs http://localhost:3000/api/opem
```
(In Claude Code the script is at `${CLAUDE_SKILL_DIR}/scripts/sign-test-delivery.mjs`.) It prints a `curl` command with the four headers and a `request.created` body signed with the secret in `OPEM_WEBHOOK_SECRET`, the same variable the handler reads; start the local server with the same test value. Use a made-up test secret here, never the endpoint's real one. Then test the real thing through a tunnel and the dashboard's "Redeliver".
6. **In another language,** compute HMAC-SHA256 with the secret over the `Opem-Timestamp` value, a full stop and the raw body, compare its lowercase hex with the part after `v1=` in constant time, and refuse a timestamp more than five minutes from the clock.
## Without the connection
When the MCP server cannot be connected, or the connection lacks `keys`, the developer adds the endpoint on the Configuration page, Webhooks tab: tell them the URL to enter and which events to tick. The secret is shown once there; they copy it into the server's environment file as `OPEM_WEBHOOK_SECRET` themselves. Steps 1 to 6 are the same.
## When verifying fails
A server clock more than five minutes out; a parsed body instead of the raw one; a rotated secret still in an old environment; a proxy that re-encodes the body. [local-testing.md](references/local-testing.md) has the checks in order.
## References
- [events.md](references/events.md): events, headers, signature, retries and timeouts
- [handler.md](references/handler.md): a verified webhook handler
- [local-testing.md](references/local-testing.md): a tunnel, the offline signer, redelivery, and the checks when verifying fails
Files in this package (5)
- SKILL.md 5 KB
- references/events.md 2 KB
- references/handler.md 1 KB
- references/local-testing.md 2 KB
- scripts/sign-test-delivery.mjs 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · agile-4/opem-agent-plugin | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| vaisala-xweather/xweather-agent-skills | 100 | MIT |
| envigoinnovations/subscriby-agentic-kit | 100 | MIT |
| ciro-maciel/ccm-stack | 100 | MIT |
| nirholas/xactions | 100 | Apache-2.0 |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| G1Joshi/Agent-Skills | 100 | MIT |
| nahid-sparktales/agent-dispatcher | 90 | MIT |
Database snapshot: 13.11.2026 · package version 02ecf0a0c849 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90onboard
Use when the developer has no Opem account or project yet, asks how to start with Opem, or holds a key (pk_, sk_, vs_) with no idea where it goes. Walks through signing up at support.opem.app, creating a project, and finding the publishable key, the allowed origins and the… - 100identify
Use when the developer wants Opem to know who the signed-in user is: Opem.identify and Opem.reset, unverified people in the inbox, HMAC signing, the verification secret (vs_), the Require signed identities and Trust unsigned roles switches, roles and signedAt, the errors… - 100meetgeek-webhooks
Receive and verify MeetGeek webhooks. Use when setting up a MeetGeek webhook handler, debugging X-MG-Signature verification, or handling meeting analysis notifications (successful-analysis and failed-analysis) from the MeetGeek Public API. - 100seatable-webhooks
Receive and verify SeaTable webhooks. Use when setting up SeaTable webhook handlers, debugging X-Seatable-Signature verification, or handling base change events (insert_row, modify_row, delete_row). - 100webhook-integration-testing
Build and test webhook integrations locally — capture real webhooks as fixtures, verify HMAC signatures correctly (including timestamp freshness against replay), replay captures at your handler while developing. Use whenever the user integrates with webhooks (Stripe, GitHub,…