Endpoints

  • POST /webhooks - create a new webhook
  • GET /webhooks - list webhooks
  • GET /webhooks/{webhookId} - get details of a webhook by webhook id
  • DELETE /webhooks/{webhookId} - delete a webhook by webhook id

Webhook object

  • id (string) - the unique identifier of the webhook
  • targetUrl (string) - the URL of the webhook endpoint on your server
  • sharedSecret (string) - a secret used to generate a signature for each request. Only returned when creating a webhook.
  • events (list of events) - the list of events enabled for this webhook

Verifying Requests

When a webhook is created with a sharedSecret, Rise will include an X-Hook-Signature header in each request, allowing you to verify that request came from Rise. To calculate the signature, Rise uses the HMAC-SHA1 algorithm with the sharedSecret and the request body as input.

Here's an example of what this might look like in Node.js:

const signature = headers['x-hook-signature'] 

const digest = crypto.createHmac('sha1', config.sharedSecret)
.update(Buffer.from(JSON.stringify(body), 'utf-8'))
.digest('hex')

if (signature === digest) {
// OK: request came from Rise
} else {
// Error: request didn't come from Rise
}

Events

course.completed - triggered when a learner completes a course.

Here's an example of what a request to the webhook endpoint on your server would look like for this event:

{ 
"id": "example-course-completed-event-id",
"createdAt": "2020-07-02T03:39:18.991Z",
"type": "course.completed",
"data": {
"course": {
"authorUrl": "https://api.rise.com/users/example-author-id",
"coverImageUrl": null,
"id": "example-course-id",
"courseReportUrl": "https://api.rise.com/reports/courses/example-course-id",
"title": "Example Course",
"url": "https://api.rise.com/courses/example-course-id"
},
"user": {
"email": "foo@example.com",
"firstName": "Example First Name",
"id": "example-user-id",
"lastName": "Example Last Name",
"learnerReportUrl": "https://api.rise.com/reports/learners/example-user-id",
"role": "learner",
"url": "https://api.rise.com/users/example-user-id"
}
}
}

Create Webhook

POST /webhooks

Parameters

  • targetUrl (string, required)
  • events (list of events, required)
  • sharedSecret (string, optional)

Example Response

{ 
"id": "example-webhook-id",
"targetUrl": "https://example.com",
"events": ["course.completed"],
"sharedSecret": "the shared secret",
"url": "https://api.rise.com/webhooks/example-webhook-id"
}

Endpoint-specific Error Codes

  • code: 'duplicate_target_url' - cannot create webhook because the targetUrl is already in use by another webhook. A 409 response will be returned in this case.

List Webhooks

GET /webhooks

Parameters

  • limit (integer, optional) - the maximum number of results to return in a single response (defaults to 50)

Example Response

{ 
"webhooks": [
{
"id": "example-webhook-id",
"targetUrl": "https://example.com",
"events": ["course.completed"],
"url": "https://api.rise.com/webhooks/example-webhook-id"
}, ...
],
"nextUrl": "https://url-for-next-page-of-results"
}

Retrieve Webhook by ID

GET /webhooks/{webhookId}

Example Response

{ 
"id": "example-webhook-id",
"targetUrl": "https://example.com",
"events": ["course.completed"],
"url": "https://api.rise.com/webhooks/example-webhook-id"
}

Endpoint-specific Error Codes

  • webhook_not_found - cannot retrieve webhook because the webhook doesn't exist

Delete Webhook by ID

DELETE /webhooks/{webhookId}

Success response

204 "No Content"

Endpoint-specific Error Codes

  • webhook_not_found - cannot delete webhook because the webhook doesn't exist
Did this answer your question?