Skip to main content

How to set up webhooks in POK

A webhook is a URL you give POK so it can call your own systems the moment something happens to a credential, instead of you asking the API over and over to check. You pick which of four events to subscribe to, and POK sends a signed request to that URL every time one of them happens, whether you issue credentials from the certifier or through the API.

Open the Webhooks section​

You need the administrator role. "Webhooks" only shows up in the menu for that role: operators and readers do not see it.

  1. In the top navigation bar, click your organization's name.
  2. In the menu that opens, click "Webhooks".

Under "Webhook List" you will find one card per event.

The four events you can subscribe to​

POK offers four events, each with its own card:

  • "Accepted Credentials" ("Receive a notification when a credential is accepted"): fires when the recipient accepts the credential.
  • "Issued Credentials" ("Receive a notification when a credential is issued"): fires once the credential is fully issued, meaning it has already been accepted, emailed to the recipient, and, for a blockchain NFT credential, minted.
  • "Electronic Signature" ("Receive a notification when a credential requires an electronic signature"): fires when a credential needs an outside signer, once POK's own signatures on it are already complete. This card only appears if electronic signature is enabled for your organization; ask your account manager if you expect it and do not see it.
  • "Learning Path Completed" ("Receive a notification when a learner completes a learning path"): fires when a learner earns every mandatory step of a Learning Path, plus the minimum number of optional steps each module asks for. It fires the same way whether or not anything is expected of your systems afterward: that depends on how you configured that particular Learning Path, not on this event. See Learning Paths for when a Learning Path expects you to act on it.

Every event names its type; credential events also carry the affected credential's id, and the Learning Path event names the path and the learner instead. Webhooks has the exact shape of each payload. To fetch the rest of a credential's details from the id it carries, call the API, which needs an API key: see API keys.

Create a webhook​

Every card works the same way:

  1. Find the card for the event you want, under "Webhook List".
  2. Type the URL in its "Webhook URL" field.
  3. Click "+ Create Webhook".

"+ Create Webhook" stays disabled until the URL looks like a real address: it needs an "http://" or "https://" scheme and an actual domain, for example https://www.example.edu/hooks/pok. A bare host or a URL without a scheme will not enable it.

You can add more than one URL to the same event. Repeat the steps and a new row appears in that card's table alongside the ones you already have; POK sends every occurrence of that event to every URL on the list, not just the newest one.

If creating a webhook fails, the URL stays in the field so you can fix it and try again without retyping it.

Once a card has at least one URL, it grows a table with "Creation Date", "Webhook URL" and "Actions" columns, one row per URL. The three icons under "Actions" (a key, a check mark and a trash can) are covered next.

The signing key and the shared secret​

Click the key icon in a row's "Actions" to open "Webhook Keys". It shows two secrets for that URL only: the "Signing Key" and the "Shared Secret". Each URL you add gets its own pair, even two URLs subscribed to the same event.

Both are hidden like a password. Click the eye icon next to one to reveal it, or the copy icon to copy it straight to your clipboard; POK confirms with "Secret copied to clipboard".

They exist so your system can confirm a request really came from POK, not from someone else, and was not altered in transit:

  • The signing key is what you use to check the request's "X-Pok-Signature" header against its body.
  • The shared secret is what comes back to you, base64-encoded, in the request's own "Authorization" header.

Webhooks has the exact steps for both, including a ready-to-use TypeScript snippet for the signature check. Because the keys are per URL, use the ones from the same row you are trying to verify: a signature checked against a different webhook's signing key will never match, even if the request is genuine.

Send a test​

Click the check mark icon on a row to send that URL a real, fully-formed request for its event, with placeholder values standing in for an actual credential or learner. It carries the same headers and the same signature a genuine event would, so it is a safe way to check an endpoint before wiring it to real traffic.

POK shows "Test sent successfully." as soon as it dispatches the request. That confirms POK queued and sent it; it does not confirm your endpoint received or accepted it, because delivery happens afterward and POK does not report that part back to the certifier. To see the test actually arrive, watch your own endpoint directly (its logs, or a request-inspection tool while you are still wiring things up).

Delete a webhook​

Click the trash can icon on a row to delete that URL. There is no confirmation step: it is gone as soon as you click it, and this cannot be undone.

If you need the same URL again later, create it again. The new webhook gets a new signing key and a new shared secret; it does not get the old ones back.

Nothing is arriving at your URL​

Work through these in order:

  1. The event has not actually happened yet. Each one fires only for its own condition, described under the four events above. "Issued Credentials", for example, needs the credential already accepted and emailed, and minted too if it is a blockchain NFT credential: creating or sending a credential is not enough on its own to fire it.
  2. The event is not on the page at all. "Electronic Signature" only appears once that feature is enabled for your organization. Ask your account manager if you expect to see it and do not.
  3. POK reached your URL, but nothing tells you what happened next. POK calls your URL once per event and does not retry. If your endpoint is down, times out, or rejects the request, nothing in the certifier shows that, not even a test: seeing "Test sent successfully." only means POK dispatched the request, not that your endpoint answered. Check your endpoint's own reachability and logs directly; sending a test while you watch them is the fastest way to tell.

A call arrives but you cannot verify it came from POK​

  1. The signature check is not running over the raw body. The HMAC has to use the request body exactly as it arrived, before your code parses it. Re-serializing the JSON, even without changing a single value, produces a different string and a different signature. Webhooks has the exact recipe and a working code sample.
  2. The keys belong to a different webhook. Every URL has its own signing key and shared secret. If your organization has more than one, verifying with the wrong row's keys makes a genuine request look invalid.