Overview
You can use webhooks to receive information about events that happen in Credly. For example, you can use webhooks to be informed when a user accepts or rejects a badge on Credly. A full list of event types is below.
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. If configured, Credly will post the event information to your server via an HTTPS POST request.
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 four 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.
- Your OAuth application must have data services enabled. Your customer success manager can ensure this is enabled for you.
- 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. - Finally, to choose which events to receive webhook notifications for, navigate to organization management and select "Developers" > "Webhooks". Here you will see all available webhooks and you can choose which ones to subscribe to.
Receiving Events
After completing the requirements above, 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.
The JSON object that Credly posts to your webhook_url will be a summary of the event and contain the following attributes:
{
"id": "628fcaa9-cfd3-4a9b-aa62-9973ac938ad6",
"organization_id": "a0d325d9-d8cb-466f-b515-c767949f7e9a",
"event_type": "badge.created",
"occurred_at": "2014-04-01T14:41:00Z"
}
You can then fetch the event object from Credly's servers using the id attribute of the payload above by making a request to
GET /organizations/<organization_id>/events/<event_id>
The response will be a 200 OK and the shape of this response will vary depending on the event type.
You can also list all events for an organization by making a request to
GET /organizations/<organization_id>/events[?page=1]
At most 50 results are returned at a time. Include an optional page parameter to fetch the next page of results.
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.account_merged: This event is triggered whenever a user merges two accounts. -
user.connect_access.removed: This event is triggered when a user removes access to an OAuth application. -
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
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 Event Detail Responses
(Note that all event detail responses will include [id, organization_id, event_type, and occured_at]. This documentation goes over what additional fields are present in the responses)
badge.* events
All badge.* event types will return information about the badge using the standard badge shape. Examples can be found in the Issued Badges Documentation
badge_template.* events
All badge_template.* event types will return information about the badge template using the standard badge template shape. Examples can be found in the Badge Templates Documentation
user.account_merged
This event will additionally include the following two attributes in the response body
{
"source_user_id": "628fcaa9-cfd3-4a9b-aa62-9973ac938ad6",
"destination_user_id": "e36a911b-f4aa-46a0-bafb-bbfd9e3329c0"
}
For this event, source_user_id is the user who was merged INTO destination_user_id. I.e destination_user_id is the id of the user who remains after the merge.
user.connect_access.removed
This event will include the following attribute:
json
{
"user_id": "628fcaa9-cfd3-4a9b-aa62-9973ac938ad6"
}
user.public_badges.*
These events will include user_id and also information about the badge using the standard badge shape. Examples can be found in the Issued Badges Documentation
These events may or may not contain additional information about user secondary emails. Contact your customer success manager for more information.
Examples
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",
"delivered_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. - 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",
"delivered_at": "2014-04-01T14:41:00Z"
}
You can now use the id to request more information about the event from Credly as mentioned above.
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
In addition to the event types listed above, the following are 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.updated: This event is triggered for a Workforce organization when an employee record is updated -
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",
"delivered_at": "2014-04-01T14:41:00Z"
}
And again, more data can be fetched by using the id of the incoming event.
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 / Employment Updated Event Response Example
Response
{
"data": {
"id": "01d9ae0c-dd5a-4515-87d7-78a01b0375c1",
"event_type": "employment.created",
"organization_id": "800ce0f3-179b-4268-bcfa-59583fe64e16",
"occurred_at": "2014-04-01T14:41:00.000Z",
"employment": {
"id": "b4061674-9aaf-425d-bdf6-0020b3a3bbc1",
"email": "email1@example.com",
"created_at": "2014-04-01T14:41:00.000Z",
"last_updated_by_organization_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": "Software Engineer",
"manager_first_name": null,
"manager_last_name": null,
"manager_external_id": "manager-000001",
"country": null,
"zip_code": null,
"state_or_province": null,
"department": "Engineering",
"job_family": "f100",
"level": null,
"organization_level_1": "Farming",
"organization_level_2": "Aquatic",
"organization_level_3": "Kelp",
"employer": {
"id": "a42de9d3-c2ee-4cf3-991c-f71141be8172",
"name": "Organization 1",
"bio": "Function-based eco-centric standardization gurus",
"industry": "J"
},
"badges": [
{
"id": "51b25934-ad0c-4478-94b6-94ae61b53acb",
"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/51b25934-ad0c-4478-94b6-94ae61b53acb/userdataservice",
"badge_template": {
"id": "c6762bd4-3c0e-42c5-827f-f04c613003b4",
"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": "b3826b92-9a8b-4ac2-83f7-bc4979e09457",
"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/b3826b92-9a8b-4ac2-83f7-bc4979e09457/userdataservice",
"badge_template": {
"id": "f22389af-50f5-4d60-9c37-90b8db19705c",
"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": "eb7b5543-2d62-4d8b-96fa-39fe9a07c787",
"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/eb7b5543-2d62-4d8b-96fa-39fe9a07c787/userdataservice",
"badge_template": {
"id": "2b67b707-27fa-4b4a-b36c-3b0a24b635db",
"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": "d3eda6bd-c847-4d08-8536-959ebd88f560",
"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/d3eda6bd-c847-4d08-8536-959ebd88f560/userdataservice",
"badge_template": {
"id": "33dc82a9-181e-4337-8cc6-4186ce5b1a7f",
"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": "844a8a65-6929-4515-bd19-0894df527b15",
"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/844a8a65-6929-4515-bd19-0894df527b15/userdataservice",
"badge_template": {
"id": "f047f70d-be43-4361-b400-a568529aa83b",
"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
}
}
],
"employment_histories": [
{
"id": "cb71ad90-c7e0-42c9-9be6-def7aa496e1f",
"current": true,
"employer_job_title": "Software Engineer",
"faethm_occupation": null,
"occupation_name": null,
"model_version": null,
"confidence_rating": null,
"state": "unmapped"
}
]
}
},
"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": "2ac78a1c-901b-4a4a-b944-13849188dcd1",
"event_type": "employment.badges.added",
"organization_id": "0d7b463b-5793-4991-927f-dd4ec62f2705",
"occurred_at": "2014-04-01T14:41:00.000Z",
"employment": {
"id": "82dd5585-784b-4c37-af35-8a52ad7209ba",
"email": "email1@example.com",
"created_at": "2014-04-01T14:41:00.000Z",
"last_updated_by_organization_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": "Software Engineer",
"manager_first_name": null,
"manager_last_name": null,
"manager_external_id": "manager-000001",
"country": null,
"zip_code": null,
"state_or_province": null,
"department": "Engineering",
"job_family": "f100",
"level": null,
"organization_level_1": "Farming",
"organization_level_2": "Aquatic",
"organization_level_3": "Kelp",
"employer": {
"id": "23cbdd04-a614-4298-9386-cd2fe2b83a23",
"name": "Organization 1",
"bio": "Function-based eco-centric standardization gurus",
"industry": "J"
},
"badges": [
{
"id": "e884fde3-8227-405d-87cb-2e8ee37e0a08",
"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/e884fde3-8227-405d-87cb-2e8ee37e0a08/userdataservice",
"badge_template": {
"id": "1fda1973-d6c6-4523-b494-39ce1b8c551f",
"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": "d0fe893b-d94f-4760-9a3a-e3f70674dea4",
"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/d0fe893b-d94f-4760-9a3a-e3f70674dea4/userdataservice",
"badge_template": {
"id": "3771f140-1129-471a-a4a1-7bbb531a1065",
"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": "5cfcc0d8-1797-4912-9962-95daf502d4bf",
"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/5cfcc0d8-1797-4912-9962-95daf502d4bf/userdataservice",
"badge_template": {
"id": "aad410a6-9653-4856-b8d5-099d179fe960",
"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": "21f8faf8-8be2-4060-82bb-e4b92d324cee",
"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/21f8faf8-8be2-4060-82bb-e4b92d324cee/userdataservice",
"badge_template": {
"id": "988a99e3-f0c7-41e1-bc1a-3160ced59358",
"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": "b442b57b-987e-41be-be85-034679f128e0",
"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/b442b57b-987e-41be-be85-034679f128e0/userdataservice",
"badge_template": {
"id": "0b595de8-2d55-48c3-94ed-9eeaff0e174b",
"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
}
},
{
"id": "aade475c-106e-4f37-bc53-a9b9149ea982",
"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/aade475c-106e-4f37-bc53-a9b9149ea982/userdataservice",
"badge_template": {
"id": "aaef241c-791b-4241-a92a-e37a4ff7b2d5",
"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
}
}
],
"employment_histories": [
{
"id": "f80e0dd0-f7c4-4dd1-9ff3-61b06fd7109f",
"current": true,
"employer_job_title": "Software Engineer",
"faethm_occupation": null,
"occupation_name": null,
"model_version": null,
"confidence_rating": null,
"state": "unmapped"
}
]
},
"badge": {
"id": "aade475c-106e-4f37-bc53-a9b9149ea982",
"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/aade475c-106e-4f37-bc53-a9b9149ea982/userdataservice",
"badge_template": {
"id": "aaef241c-791b-4241-a92a-e37a4ff7b2d5",
"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": {
}
}