Webhook configuration

A webhook automatically notifies an external system (your backend, an LMS, a CRM) every time an event happens on your digital credentials — for example, when someone accepts a credential — without you having to poll Acreditta’s API periodically to find out.

Where to configure them

  1. Go to Settings → Integrations → API.
  2. Open the Webhooks tab.

🔎 Note: this lives under the API tab, not External Tools — that other section is for login and LMS integrations (Microsoft, Google, Moodle, Canvas, etc.), a different topic.

⚠️ Important: webhooks require a plan that includes this capability. If your organization doesn’t have it, any call to the webhooks API responds with 400 and this tab is replaced with a notice to upgrade your plan. See Plans and limits.

If you don’t have any configured yet, you’ll see the message “No webhooks configured.” Click + New Webhook to create your first one.

Create a webhook

Fill in:

  • Endpoint URL (Web Service): the address of your system that will receive the notification. Required.
  • Authentication type: how your backend will validate that the notification really comes from Acreditta.
  • Events: what you’ll listen for. You must select at least one.

Authentication types

  • HMAC Signature (Recommended): Acreditta generates a Secret Key when you save the webhook, which you use in your backend to validate that each notification is correctly signed. It’s the most secure option.
  • Bearer Token: token-based authentication in the request header.
  • Basic Auth: username and password.
  • No authentication: the endpoint receives the notification with no additional validation. Only recommended if your endpoint isn’t publicly accessible or you already protect it some other way.

⚠️ Important: with HMAC Signature, Acreditta signs each notification with a Secret Key unique to that webhook (you’ll see the signature in the X-Hub-Signature-256 header of every request). That’s the value your backend needs to validate the authenticity of each notification — keep it somewhere safe.

Available events

Events are grouped into two blocks, and you can select as many as you need (or use “Select all” within each block):

Credentials:
– Accepted
– Pending
– Failed
– Revoked
– Expired
– Versioned

Batch issuances:
– Started — the issuance batch begins processing.
– Completed — the issuance batch finishes processing and reports the status of the deliveries.

Click Save Webhook to finish.

After saving it

The webhook appears in the list with its URL, authentication type, and subscribed events:

🔎 Note: the webhook is created with Inactive status. Check this state in the list before considering it configured.

From the icons in that same row you can edit the configuration, test the webhook, activate or deactivate it, and delete it.

Test the webhook

Before relying on a webhook in production, you can trigger a test notification against your endpoint from the corresponding icon in the row. Acreditta shows you the full detail of the request sent and the response received (or the error, if your endpoint didn’t respond):

  • Endpoint URL and webhook UUID being tested.
  • Headers of the request, including the X-Hub-Signature-256 signature when using HMAC Signature.
  • Body of the request — for example, for the “Pending” event:
{
  "scope": "credentials",
  "subscope": "status_pending",
  "timestamp": "2026-09-04T23:18:17.834069+00:00",
  "data": {
    "badge_uuid": "73b127b1-e913-40c4-abd7-3b85453d1d76",
    "new_status": "pending",
    "previous_status": "generating"
  }
}
  • Response detail from your server, or the error message if the connection couldn’t be made (for example, if the domain doesn’t exist or doesn’t respond).

🔎 Note: this test is the fastest way to confirm your backend correctly receives and validates the signature before turning on the webhook for real.

Delivery resilience

Design your backend assuming a notification might not arrive — for example, if your endpoint is down at the exact moment the event happens. Don’t assume Acreditta will automatically retry a failed delivery; if your integration depends on not missing any event, complement webhooks with a periodic call to the API (for example, /report/credential/status) to reconcile the real status of your credentials.

🔎 Note: if you have questions about the exact retry behavior for your case, write to us at tech@acreditta.com before building your integration around a specific number of retries.


CONTENIDO

Powered By EazyDocs