Skip to content
Skills Library
Programming · Tool integration

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.

Licence
MIT
Last repository change
10.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
1
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. First: is Opem connected?
  2. Stop at the chosen step
  3. Before you start
  4. Steps
  5. Without the connection
  6. When verifying fails
  7. References
Original SKILL.md headings · 49 lines, 696 words
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

RepositoryScoreLicence
This page · agile-4/opem-agent-plugin100MIT
ericrisco/rsc-harness100MIT
vaisala-xweather/xweather-agent-skills100MIT
envigoinnovations/subscriby-agentic-kit100MIT
ciro-maciel/ccm-stack100MIT
nirholas/xactions100Apache-2.0
claude-dev-suite/claude-dev-suite100MIT
G1Joshi/Agent-Skills100MIT
nahid-sparktales/agent-dispatcher90MIT

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,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.