agentsclimarketplace

Igrantio backend webhooks

Skill L3-iGrant/skills/ows/igrantio-backend-webhooks

Agent Skills for EUDI Wallet and European Business Wallet integrations: credential issuance (OpenID4VCI), verification (OpenID4VP + DCQL), DC API and consent management on the iGrant.io Organisation Wallet Suite

Install
npx -y skills add L3-iGrant/skills --skill igrantio-backend-webhooks

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 22 days oldThe repository was created 22 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Composable building block: register, receive, and verify iGrant.io OWS digital-wallet webhooks for OpenID4VCI issuance and OpenID4VP verification events. Idempotently create a webhook via config-create-webhook (skip if one already targets the payloadUrl), verify the X-iGrant-Signature HMAC-SHA256, map each topic to its exchange id (CredentialExchangeId / presentationExchangeId), and store the event. Use to add OWS webhook handling to any Node/TypeScript backend.

The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.9 KB, as published. Nobody here has run it

iGrant.io backend webhooks (register + receive + verify)

When to use

Whenever your backend must be notified when a wallet completes an issuance or verification. Pairs with igrantio-backend-sse (which streams the stored events to the browser). Composed by igrantio-issuer-backend / igrantio-verifier-backend.

Before you build: run the integrator intake in igrantio-ows-overview - environment, API key, tenancy, backend host, webhooks, frontend - one question at a time, a recommended default with each.

What it does

  • Register (idempotent) - POST /v2/config/webhook with payloadUrl, contentType, subscribedEvents.digitalWalletWebhook, secretKey. Lists existing webhooks first and skips if one already targets the payloadUrl.
  • Receive - POST /webhook: verify X-iGrant-Signature: t=<ts>,sig=<hex> where sig = HMAC_SHA256(secretKey, "<t>.<raw body>") (constant-time compare), reject unknown topics, extract the exchange id, store the event.

Reference

./references:

  • topics.ts - ISSUER_TOPICS, VERIFIER_TOPICS, extractExchangeId(type, data).
  • webhooks.ts - verifySignature(...) + webhookReceiver(store) router.
  • registerWebhook.ts - registerWebhook({ owsBaseUrl, apiKey, payloadUrl, secretKey, topics }), idempotent.
  • eventStore.ts - the EventStore the receiver writes to (shared with SSE).
  • config.ts - webhookSecretKey, OWS base URL.

Topics → exchange id

TopicExchange id path in data
openid.credential.offer_received / token_issued / credential_acked / credential_acceptedcredential.CredentialExchangeId
openid.presentation.presentation_acked.v3 / digitalwallet.presentation.verifiedpresentation.presentationExchangeId

Register once per org (idempotent)

await registerWebhook({
  owsBaseUrl: config.owsBaseUrl,
  apiKey: "<org OWS key>",
  payloadUrl: "https://your-backend/webhook",
  secretKey: config.webhookSecretKey,   // MUST match the receiver
  topics: [...ISSUER_TOPICS],            // or VERIFIER_TOPICS, or both
});

Re-running is safe: it lists existing webhooks and skips creation if the payloadUrl is already registered.

Clean-code notes

  • Signature verification is constant-time; the secret lives only in config.
  • Topic knowledge (names + exchange-id extraction) is isolated in topics.ts.

Validation / done criteria

  • A tampered body or wrong secret → 401. A supported topic with a valid signature → stored under its exchange id. An unsupported topic → 400.
  • Registering twice creates exactly one webhook.

Documentation & workflows

When anything is unclear, consult the iGrant.io documentation before guessing:

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.