Overview
You can use webhooks to receive information about events that happen in Credly. You can use webhooks to be informed when a user accepts or rejects a badge on Credly, for example.
When an event occurs, Credly creates an event object to keep track of the type of event, the time when it occurred, and the data associated with the event. Credly can post the event information to your server via an HTTPS POST request. A full list of event types is below.
When sending webhooks, Credly will wait for a success response for a short time, after which the delivery will be considered a failure, and the event will re-queued for later delivery. We recommend using a message queue or other means of processing webhooks asynchronously, to maximize the reliability and timeliness of webhook deliveries.
Configuration
Requirements
There are two requirements to enable webhooks:
- You must create a page on your website or server that can receive an HTTPS POST request from Credly. This page must be publicly visible (as to be accessible by Credly's servers), and it should be configured to receive JSON data via HTTPS POST. Your endpoint must use a valid signed SSL certificate.
- You must update your organization profile to specify the
webhook_urlattribute. Credly will post a JSON object to the URL you specify whenever an event occurs.
Receiving Events
After you specify your webhook_url, Credly will automatically begin posting events to your server. Your server must return an HTTP status code of 200 to indicate that the webhook was received. If Credly 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
Credly 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 Credly user interface. -
badge.deleted: This event is triggered whenever a badge is deleted. This should rarely occur. Usually a badge will change itsstatetorevokedorreplacedinstead. -
badge.privacy.changed: This event is triggered whenever a user changes the privacy setting for a badge. -
badge.state.changed: This event is triggered whenever thestateof a badge changes. When the user accepts a badge, for example, thestatechanges frompendingtoaccepted. -
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. -
user.public_badges.changed: This event is triggered whenever a user has changes to their set of publicly viewable badges. -
user.public_badges.added: This event is triggered when a badge becomes visible via Credly Connect -
user.public_badges.removed: This event is triggered when a badge becomes invisible via Credly Connect -
employment.badges.added: This event is triggered for a Workforce organization when a badge associated with an employee becomes viewable to the employer -
employment.badges.removed: This event is triggered for a Workforce organization when a badge associated with an employee becomes not viewable to the employer -
employment.badges.state_changed: This event is triggered for a Workforce organization when a badge associated with an employee viewable to the employer has its state updated -
employment.badges.privacy_changed: This event is triggered for a Workforce organization when a badge associated with an employee viewable to the employer has its privacy status updated -
employment.created: This event is triggered for a Workforce organization when an employee record is created -
employment.deleted: This event is triggered for a Workforce organization when an employee record is destroyed -
employment.connection.pending: This event is triggered for a Workforce organization when an employee enters the "pending" state, meaning they will see a prompt to connect with their employer when they log into Credly. -
employment.connection.accepted: This event is triggered for a Workforce organization when an employee accepts their connection to the employer. Employers will now be able to potentially view badges from other issuers associated to the employee. -
employment.connection.rejected: This event is triggered for a Workforce organization when the connection is rejected. -
employment.user_account.associated: This event is triggered for a Workforce organization when an employee record is associated with a Credly User Account. Employers will now be able to potentially view badges associated with the employees personal Credly account. -
employment.user_account.disassociated: This event is triggered for a Workforce organization when an employee record has become disassociated with its Credly User Account
You can choose which events you would like to receive notifications for in "Organization Management" › "Developers" › "Webhooks".
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 Credly user interface.
- Credly generates an
eventand posts the data to yourwebhook_url. Here's an example webhook payload:
Badge Created Webhook
Request Body
{
"id": "628fcaa9-cfd3-4a9b-aa62-9973ac938ad6",
"organization_id": "a0d325d9-d8cb-466f-b515-c767949f7e9a",
"event_type": "badge.created",
"occurred_at": "2014-04-01T14:41:00Z"
}
- Your server responds with HTTP status code 200 to Credly.
- You can optionally use the event's
idto request more information about the event from Credly. Please refer to the web service documentation for Organizations for details. - Sometime later, the user accepts the badge via the Credly user interface.
- Credly generates an
eventand posts the data to yourwebhook_url.
Badge State Changed Webhook
Request Body
{
"id": "9e2ab7e1-c690-4756-b683-ee99a8b49b6c",
"organization_id": "1e2a5091-a445-4a46-b8ba-85906b401172",
"event_type": "badge.state.changed",
"occurred_at": "2014-04-01T14:41:00Z"
}
- You can optionally use the event's
idto request more information about the event from Credly. Please refer to the web service documentation for Organizations for details.
Workforce
Credly allows organizations to receive webhooks specific to the context of events related to employees to accommodate the syncing of employee and badge data for Workforce Organizations.
Workforce Event Types
The following are the workforce event types that will trigger a webhook to be sent to an organizations webhook url.
-
employment.badges.added: This event is triggered for a Workforce organization when a badge associated with an employee becomes viewable to the employer -
employment.badges.removed: This event is triggered for a Workforce organization when a badge associated with an employee becomes not viewable to the employer -
employment.badges.state_changed: This event is triggered for a Workforce organization when a badge associated with an employee viewable to the employer has its state updated -
employment.badges.privacy_changed: This event is triggered for a Workforce organization when a badge associated with an employee viewable to the employer has its privacy status updated -
employment.created: This event is triggered for a Workforce organization when an employee record is created -
employment.deleted: This event is triggered for a Workforce organization when an employee record is destroyed -
employment.connection.pending: This even is triggered for a Workforce organization when an employee enters the "pending" state, meaning they will see a prompt to connect with their employer when they log into Credly. -
employment.connection.accepted: This event is triggered for a Workforce organization when an employee accepts their connection to the employer. Employers will now be able to potentially view badges from other issuers associated to the employee. -
employment.connection.rejected: This event is triggered for a Workforce organization when the connection is rejected. -
employment.user_account.associated: This event is triggered for a Workforce organization when an employee record is associated with a Credly User Account. Employers will now be able to potentially view badges associated with the employees personal Credly account. -
employment.user_account.disassociated: This event is triggered for a Workforce organization when an employee record has become disassociated with its Credly User Account
Employment Created Webhook
Similar to non workforce webhooks, when an action occurs on Credly that triggers a webhook request (e.g. an employment record is created on Credly), then the initial payload to the organization's webhook url will look like the following:
Request Body
{
"id": "8fce56cf-f11b-460d-a523-c73984e3699e",
"organization_id": "12bc9b3a-0f49-4e7e-ba9e-e5ca73fa1513",
"event_type": "employment.created",
"occurred_at": "2014-04-01T14:41:00Z"
}
Workforce Event Api Responses
The response from the Events api will return varying data dependent on the event_type as well as whether or not the organization making the request
is still authorized to access Workforce data (i.e. is still a Workforce Organization).
For all event_types except employment.badges.added, employment.badges.removed, and employment.deleted. The response from the Events api
when querying for a Workforce event will show full data related to the employee including all badges associated with the employee viewable to the employer.
Employment Created Event Response Example
Response
{
"data": {
"id": "cb1de9ac-1086-466a-ac4d-a91312ca1577",
"event_type": "employment.created",
"organization_id": "ca5f866b-aaa6-4a55-b0f6-9892a3e09b88",
"occurred_at": "2014-04-01T14:41:00.000Z",
"employment": {
"id": "ba5cb1ed-0793-4164-a68b-a3fea142051e",
"email": "email1@example.com",
"created_at": "2014-04-01T14:41:00.000Z",
"employee_state": "accepted",
"employee_state_updated_at": "2014-04-01T14:41:00.000Z",
"last_invitation_sent_at": null,
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"photo_url": null,
"team": null,
"external_id": "ext-id",
"position_title": null,
"manager_first_name": null,
"manager_last_name": null,
"manager_external_id": null,
"country": null,
"zip_code": null,
"state_or_province": null,
"department": "Engineering",
"badges": [
{
"id": "faa0629c-55f3-4293-9964-9346e22d2edd",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/faa0629c-55f3-4293-9964-9346e22d2edd/userdataservice",
"badge_template": {
"id": "83a895ad-1ef6-4b39-a8b7-e102c6c48926",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 3",
"skills": [
"Skill 7",
"Skill 8",
"Skill 9"
]
},
"issuer": {
"name": "Organization 4",
"image_url": null
}
},
{
"id": "202f48ae-3379-4eec-aae2-24770544bc66",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/202f48ae-3379-4eec-aae2-24770544bc66/userdataservice",
"badge_template": {
"id": "9d9387c7-095c-419f-b6f6-04abab80b565",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 4",
"skills": [
"Skill 10",
"Skill 11",
"Skill 12"
]
},
"issuer": {
"name": "Organization 5",
"image_url": null
}
},
{
"id": "44a515e7-ece6-497e-b1d0-6ab93a6997eb",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/44a515e7-ece6-497e-b1d0-6ab93a6997eb/userdataservice",
"badge_template": {
"id": "a32ab6dc-c4af-4ff5-a97b-2ec3713a98cc",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 1",
"skills": [
"Skill 1",
"Skill 2",
"Skill 3"
]
},
"issuer": {
"name": "Organization 2",
"image_url": null
}
},
{
"id": "3fd71e3e-df71-43d6-8721-ce5b664f8506",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/3fd71e3e-df71-43d6-8721-ce5b664f8506/userdataservice",
"badge_template": {
"id": "0a02c83a-7323-4290-a8ac-ce346ef1a5c3",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 2",
"skills": [
"Skill 4",
"Skill 5",
"Skill 6"
]
},
"issuer": {
"name": "Organization 3",
"image_url": null
}
},
{
"id": "c5e12bab-e4d4-4762-abbf-02200a44db84",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/c5e12bab-e4d4-4762-abbf-02200a44db84/userdataservice",
"badge_template": {
"id": "02263704-7593-4436-bf10-3a623bd95fd0",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 5",
"skills": [
"Skill 13",
"Skill 14",
"Skill 15"
]
},
"issuer": {
"name": "Organization 6",
"image_url": null
}
}
]
}
},
"metadata": {
}
}
For event_types employment.badges.added and employment.badges.removed, the response will show everything as shown above, as well as
information specific to the badge that was added or removed from an employers visibility.
Employment Badge Added / Removed Response Example
Please note! The employment.badges.added and employment.badges.removed webhooks will not encompass all
possible events that may change the badges that an employer can see for an employee in the Credly platform. That is,
if you solely rely on these two events you may have un-synced badge information. What these two events cover are actions that affect
the visibility of a singular badge such as a badge being issued to the employee, or an employee updating
the privacy settings of a single badge. What it does not cover are "one time" events such as when the employee accepts their connection
to the employer, which may cause multiple additional badges to become visible to the employer. In this case
we encourage the integrator to do a one time refresh of all badges that the employee which we show in the
badges section of the employment object when querying the events api.
Response
{
"data": {
"id": "385b6841-7c81-4d2b-96ec-7e98712343ef",
"event_type": "employment.badges.added",
"organization_id": "df1c2d25-8f5f-4ee4-b8e0-6c308365601c",
"occurred_at": "2014-04-01T14:41:00.000Z",
"employment": {
"id": "02fc4551-394c-433c-83df-6b4d8c399077",
"email": "email1@example.com",
"created_at": "2014-04-01T14:41:00.000Z",
"employee_state": "accepted",
"employee_state_updated_at": "2014-04-01T14:41:00.000Z",
"last_invitation_sent_at": null,
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"photo_url": null,
"team": null,
"external_id": "ext-id",
"position_title": null,
"manager_first_name": null,
"manager_last_name": null,
"manager_external_id": null,
"country": null,
"zip_code": null,
"state_or_province": null,
"department": "Engineering",
"badges": [
{
"id": "f0a1ca9a-51a4-4ce3-b850-712b176d7e53",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/f0a1ca9a-51a4-4ce3-b850-712b176d7e53/userdataservice",
"badge_template": {
"id": "f3790634-6c23-4264-b2c9-bd5e81e70029",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 6",
"skills": [
"Skill 16",
"Skill 17",
"Skill 18"
]
},
"issuer": {
"name": "Organization 7",
"image_url": null
}
},
{
"id": "3cf6007d-38ce-46df-a585-f4d5884a3d45",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/3cf6007d-38ce-46df-a585-f4d5884a3d45/userdataservice",
"badge_template": {
"id": "11cf7fda-28b9-4c1f-a895-e73ca96e77bc",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 1",
"skills": [
"Skill 1",
"Skill 2",
"Skill 3"
]
},
"issuer": {
"name": "Organization 2",
"image_url": null
}
},
{
"id": "fed86529-a747-4fc0-b7e2-899d1b5fd532",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/fed86529-a747-4fc0-b7e2-899d1b5fd532/userdataservice",
"badge_template": {
"id": "cd868b8f-b2be-41b4-8c9e-8f52d13c0e45",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 2",
"skills": [
"Skill 4",
"Skill 5",
"Skill 6"
]
},
"issuer": {
"name": "Organization 3",
"image_url": null
}
},
{
"id": "d0c16055-474a-4a06-9153-c23f42a06c7e",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/d0c16055-474a-4a06-9153-c23f42a06c7e/userdataservice",
"badge_template": {
"id": "fd0595f7-84f2-478e-beae-51d3ce477f25",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 3",
"skills": [
"Skill 7",
"Skill 8",
"Skill 9"
]
},
"issuer": {
"name": "Organization 4",
"image_url": null
}
},
{
"id": "1d8260e9-a233-4c4b-b37c-4d6bc67cdd63",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/1d8260e9-a233-4c4b-b37c-4d6bc67cdd63/userdataservice",
"badge_template": {
"id": "e1541f79-83a4-4e1d-b3b8-f69e798dd07c",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 4",
"skills": [
"Skill 10",
"Skill 11",
"Skill 12"
]
},
"issuer": {
"name": "Organization 5",
"image_url": null
}
},
{
"id": "7d5224b7-2be7-4a6b-ab8c-bccac09b2a28",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/7d5224b7-2be7-4a6b-ab8c-bccac09b2a28/userdataservice",
"badge_template": {
"id": "2d2aecf9-834c-40a0-a8fb-772ecdfd8188",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 5",
"skills": [
"Skill 13",
"Skill 14",
"Skill 15"
]
},
"issuer": {
"name": "Organization 6",
"image_url": null
}
}
]
},
"badge": {
"id": "f0a1ca9a-51a4-4ce3-b850-712b176d7e53",
"issued_to": "Alfred Beaker Skiles",
"issued_to_first_name": "Alfred",
"issued_to_middle_name": "Beaker",
"issued_to_last_name": "Skiles",
"issued_at": "2014-04-01T14:41:00.000Z",
"expires_at": "2016-04-01T14:41:00.000Z",
"state": "accepted",
"public": true,
"badge_url": "https://localhost/badges/f0a1ca9a-51a4-4ce3-b850-712b176d7e53/userdataservice",
"badge_template": {
"id": "f3790634-6c23-4264-b2c9-bd5e81e70029",
"image": null,
"image_url": null,
"description": "Dynamically deliver go forward e-tailers",
"name": "Badge Template 6",
"skills": [
"Skill 16",
"Skill 17",
"Skill 18"
]
},
"issuer": {
"name": "Organization 7",
"image_url": null
}
}
},
"metadata": {
}
}
For event_types employment.deleted OR if the organization is not authorized to access Workforce data the response will show
minimal data related to the employee.
Employment Deleted / Not Workforce Authorized Example
Response
{
"data": {
"id": "af9f4f5c-b529-475b-86b0-04726b6f95d9",
"event_type": "employment.deleted",
"organization_id": "ace84d25-df7c-46ad-91f0-77afc9b279ed",
"occurred_at": "2014-04-01T14:41:00.000Z",
"employment": {
"id": "2dc325fc-f561-4277-b4cf-d0790d633c3f",
"email": "email1@example.com",
"external_id": "ext-id"
}
},
"metadata": {
}
}