Skip to content

Webhooks

Overview

You can use webhooks to receive information about events that happen in Acclaim. You can use webhooks to be informed when a user accepts or rejects a badge on Acclaim, for example.

When an event occurs, Acclaim creates an event object to keep track of the type of event, the time when it occurred, and the data associated with the event. Acclaim can post the event information to your server via an HTTPS POST request. A full list of event types is below.

Configuration

Requirements

There are two requirements to enable webhooks:

  1. You must create a page on your website or server that can receive an HTTPS POST request from Acclaim. This page must be publicly visible (as to be accessible by Acclaim's servers), and it should be configured to receive JSON data via HTTPS POST. Your endpoint must use a valid signed SSL certificate.
  2. You must update your organization profile to specify the webhook_url attribute. Acclaim will post a JSON object to the URL you specify whenever an event occurs.

Receiving Events

After you specify your webhook_url, Acclaim will automatically begin posting events to your server. You server must return an HTTP status code of 200 to indicate that the webhook was received. If Acclaim receives any other status code or no response, the webhook will automatically be retried at progressively less frequent intervals up to 25 days after the first attempt.

Event Types

Acclaim will notify you about the following events:

  • badge.created: This event is triggered whenever a badge is issued. A badge might be created via the web service or via the Acclaim user interface.
  • badge.deleted: This event is triggered whenever a badge is deleted. This should rarely occur. Usually a badge will change its state to revoked or replaced instead.
  • badge.state.changed: This event is triggered whenever the state of a badge changes. When the user accepts a badge, for example, the state changes from pending to accepted.
  • badge_template.created: This event is triggered whenever a badge template is created.
  • badge_template.changed: This event is triggered whenever a badge template is changed.
  • badge_template.deleted: This event is triggered whenever a badge template is delete.
  • pending_badge_notification.sent: This event is triggered whenever a user is notified of a pending badge.
  • pending_badge_notification.no_user.sent: This event is triggered whenever an email is sent to a non registered user for a pending badge.
  • pending_badge_notification.unconfirmed_email.sent: This event is triggered whenever an unconfirmed user is notified of a pending badge.

Note on badge.* event types

When you receive webhook events that are related to a badge, here are a few things to keep in mind:

  • Events might include badges issued on your behalf by an authorized issuer
  • Events might include badges you issued on behalf of another organization

Example

Here's the workflow as it relates to webhooks when you issue a user a badge and they accept it:

  • You issue a badge to a user via the web service or Acclaim user interface.
  • Acclaim generates an event and posts the data to your webhook_url. Here's an example webhook payload:
{
  "id": "4247cc4b-1f08-4595-bdff-18ea331bad21",
  "organization_id": "d221362b-2f39-4577-8ab2-60b9db7819bc",
  "event_type": "badge.created",
  "occurred_at": "2013-05-08T18:08:25Z"
}
  • Your server responds with HTTP status code 200 to Acclaim.
  • You can optionally use the event's id to request more information about the event from Acclaim. Please refer to the web service documentation for Organizations for details.
  • Sometime later, the user accepts the badge via the Acclaim user interface.
  • Acclaim generates an event and posts the data to your webhook_url.
{
  "id": "f600dc3b-d3f5-4e04-b1b1-37209b392a33",
  "organization_id": "d221362b-2f39-4577-8ab2-60b9db7819bc",
  "event_type": "badge.state.changed",
  "occurred_at": "2013-06-08T04:32:23Z"
}
  • You can optionally use the event's id to request more information about the event from Acclaim. Please refer to the web service documentation for Organizations for details.