O que esse endpoint de API faz

Os eventos de webhook enviam informações sobre a conclusão do curso, o envio do curso para publicação, a inscrição de usuários e grupos em cursos e planos de aprendizagem ou quando um usuário é adicionado à sua conta do Reach 360. Os usuários configuram a API Webhooks para recuperar as informações coletadas por esses eventos.

Tipos de eventos

• course.completed- Acionada quando um aluno conclui um curso.
• course.submitted- Acionada quando um autor envia um curso para ser revisado por um administrador para publicação.
• enrollments.created- Acionada quando usuários ou grupos estão matriculados em um curso ou plano de aprendizado.
• user.created- Acionada quando um usuário é adicionado à sua conta do Reach 360.

Carga útil do evento do Webhook

A carga útil de cada solicitação de webhook tem uma estrutura comum compartilhada por todos os eventos de webhook. O corpo da solicitação contém as seguintes propriedades:

• id(string) - o identificador exclusivo do evento
• createdAt(string) - a hora em que o evento aconteceu
• type(string) - o tipo de evento webhook
• webhookId(string) - o id do webhook que resultou no envio do evento
• apiVersion(string) - Versão da API usada ao enviar o evento webhook. Também será enviado como API-Version cabeçalho na solicitação
• data(objeto) - específico para o tipo de evento de webhook (veja exemplos)

Exemplos de carga útil de solicitação

Cada exemplo de evento de webhook abaixo mostra um exemplo de como seria uma solicitação de webhook para o URL de destino em seu servidor.

course.completed

Acionada quando um aluno conclui um curso.

Propriedades dos dados da carga útil do evento:

• curso (objeto) - o Objeto do curso para o curso relacionado ou nulo se as matrículas forem para um plano de aprendizado. Esse objeto do curso também tem um objeto de questionário com duas propriedades: aprovação e pontuação. Se não houver nenhum questionário associado ao curso, o objeto ficará vazio.

• user (object) - o objeto de usuário para o usuário relacionado.

{
“id”: “example-course-completed-event-id”, “createdAt”: 
 “2020-07-02T 03:39:18.991 Z”, “type”: “course.completed”, “webhookID”: “
example-webhook-id”, 
 “
apiVersion”: “2023-04-04", “
data”: {“curso”: {“autor URL”: "https://api.reach360.com/users/example-author-id “, “coverImageUrl”: null, “id”: “example-course-id”, “courseReportUrl”: "https://api.reach360.com/reports/courses/example-course-id “, “title”: “Exemplo de 
 curso”, 
 “url”:” 
 
 
 
 
 https://api.reach360.com/courses/example-course-id “, 
 “contentType”: “RISE” 
 “quiz”: 
 {“passed”: true
, “score”: 
 80
}}, “user”: {“email”: "foo@example.com “
, “firstName”: “Exemplo de nome”, “groupsURL”: "https://api.reach360.com/users/example-user-id/groups “, “id”: “example-user-id”
, “lastName”: “Exemplo de sobrenome”
, “lastActiveName” Em”: “2021-10-28T 20:39:52.659 Z”
, “LearnerReportUrl”: "https://api.reach360.com/reports/learners/example-user-id “, 
 
 
“função”: “aluno”, “url”: "https://api.reach360.com/users/example-user-id 
 “, 
 “Articulate360User”: false}}} 
 
 

course.submitted

Acionada quando um autor envia um curso para ser revisado por um administrador para publicação.

{
  "id": "example-course-submitted-event-id",
  "createdAt": "2020-09-14T05:47:28.951Z",
  "type": "course.submitted",
  "webhookId": "example-webhook-id",
  "apiVersion": "2023-04-04 ",
  "data": {
    "isInitialSubmission": true,
    "course": {
      "authorUrl": "<https://api.reach360.com/users/example-author-id>",
      "coverImageUrl": null,
      "id": "example-course-id",
      "courseReportUrl": "<https://api.reach360.com/reports/courses/example-course-id>",
      "title": "Example Course",
      "url": "<https://api.reach360.com/courses/example-course-id>",
	  "contentType": "RISE" 
    },
    "submitter": {
      "email": "author@example.com",
      "firstName": "Example",
      "groupsUrl": "<https://api.reach360.com/users/example-author-id/groups>",
      "id": "example-author-id",
      "lastName": "Author",
      "lastActiveAt": "2021-10-28T20:39:52.659Z",
      "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-author-id>",
      "role": "author",
      "url": "<https://api.reach360.com/users/example-author-id>"
 “Articulate360User”: false “Articulate360User”: false 
    },
    "reviewer": {
      "email": "admin@example.com",
      "firstName": "Example",
      "groupsUrl": "<https://api.reach360.com/users/example-admin-id/groups>",
      "id": "example-admin-id",
      "lastName": "Admin",
      "lastActiveAt": "2021-10-28T20:39:52.659Z",
      "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-admin-id>",
      "role": "admin",
      "url": "<https://api.reach360.com/users/example-admin-id>"
 
    }
  }
}

enrollments.created

Acionada quando usuários ou grupos estão matriculados em um curso ou plano de aprendizado.

A carga útil desse evento sempre contém os mesmos nomes de propriedades, mas quais dessas propriedades têm valores variam de acordo com o tipo de inscrições que foram criadas.

Por exemplo, se um ou mais usuários estiverem matriculados em um curso, a data parte da carga enviada ao seu manipulador incluirá uma propriedade de matriz (uma users matriz de objetos de usuário) e uma propriedade. course Nesse cenário, a groups propriedade será uma matriz vazia e learningPath será definida comonull.

Da mesma forma, se um ou mais grupos estiverem matriculados em um plano de aprendizado, o data objeto terá uma propriedade de groups matriz (uma matriz de objetos de grupo) e uma learningPath propriedade, enquanto users será uma matriz vazia e course seránull.

Propriedades dos dados da carga útil do evento:

• curso (objeto) - o Objeto do curso para o curso relacionado ou null se as matrículas forem para um plano de aprendizado.
• LearningPath (objeto) - o objeto do plano de aprendizado para o plano de aprendizado relacionado ou null se as matrículas forem para um curso.
• EnrolledBy (object) - O objeto de usuário do usuário que criou as matrículas ou null se a inscrição foi criada por meio da API de inscrições do curso ou da API de inscrições do Learning Path.
• grupos (lista de objetos) - Uma lista de objetos de grupo que foram inscritos (pode estar vazia).
• usuários (lista de objetos) - Uma lista de objetos de usuário que foram registrados (pode estar vazia).

{
  "id": "example-enrollments-created-event-id",
  "type": "enrollments.created",
  "createdAt": "2020-09-16T19:59:55.912Z",
  "data": {
    "course": {
      "authorUrl": "<https://api.reach360.com/users/example-author-id>",
      "coverImageUrl": null,
      "id": "example-course-id",
      "courseReportUrl": "<https://api.reach360.com/reports/courses/example-course-id>",
      "title": "Example Course",
      "url": "<https://api.reach360.com/courses/example-course-id>"
	  "source": "rise" 
    },
    "enrolledBy": {
      "email": "admin@example.com",
      "firstName": "Example",
      "groupsUrl": "<https://api.reach360.com/users/example-admin-id/groups>",
      "id": "example-admin-id",
      "lastName": "Admin",
			"lastActiveAt": "2021-10-28T20:39:52.659Z",
      "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-admin-id>",
      "role": "admin",
      "url": "<https://api.reach360.com/users/example-admin-id>"
“Articulate360User”: false 
    },
    "groups": [],
    "learningPath": null,
    "users": [
      {
        "email": "learner1@example.com",
        "firstName": "Foo",
        "groupsUrl": "<https://api.reach360.com/users/example-learner-1/groups>",
        "id": "example-learner-1",
        "lastName": "Learner",
				"lastActiveAt": "2021-10-28T20:39:52.659Z",
        "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-learner-1>",
        "role": "learner",
        "url": "<https://api.reach360.com/users/example-learner-1>"
 “Articulate360User”: false “Articulate360User”: false 
      },
      {
        "email": "learner2@example.com",
        "firstName": "Bar",
        "groupsUrl": "<https://api.reach360.com/users/example-learner-2/groups>",
        "id": "example-learner-2",
        "lastName": "Learner",
				"lastActiveAt": "2021-10-28T20:39:52.659Z",
        "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-learner-2>",
        "role": "learner",
        "url": "<https://api.reach360.com/users/example-learner-2>"
 “Articulate360User”: false 2023-04-04   
      },
		{
        "email": "learner3@example.com",
        "firstName": "Baz",
        "groupsUrl": "<https://api.reach360.com/users/example-learner-3/groups>",
        "id": "example-learner-3",
        "lastName": "Learner",
				"lastActiveAt": "2021-10-28T20:39:52.659Z",
        "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-learner-3>",
        "role": "learner",
        "url": "<https://api.reach360.com/users/example-learner-3>"
   
      },
    ]
  },
  "apiVersion": " ",
  "webhookId": "example-webhook-id"
}

user.created

Observação: user.created os eventos serão atrasados para usuários de SSO em 5 a 10 minutos.

Observação: user.created os eventos NÃO são acionados para usuários do SAML que são removidos do seu IDP e adicionados novamente, a menos que também sejam removidos da sua conta do Reach.

Acionada quando um usuário é adicionado à sua conta do Reach 360.

{
  "id": "example-user-created-event-id",
  "createdAt": "2020-08-24T01:36:18.982Z",
  "type": "user.created",
  "webhookId": "example-webhook-id",
  "apiVersion": "2023-04-04 ",
  "data": {
    "user": {
      "email": "foo@example.com",
      "firstName": "Example First Name",
      "groupsUrl": "<https://api.reach360.com/users/example-user-id/groups>",
      "id": "example-user-id",
      "lastName": "Example Last Name",
			"lastActiveAt": "2021-10-28T20:39:52.659Z",
      "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-user-id>",
      "role": "learner",
      "url": "<https://api.reach360.com/users/example-user-id>"
      "articulate360User": false  
 
    }
  }
}

Verificando solicitações

Quando um webhook é criado com umsharedSecret, o Reach 360 inclui um X-Hook-Signature cabeçalho em cada solicitação, permitindo que você verifique se ela veio do Reach. Para calcular a assinatura, o Reach usa um resumo hexadecimal HMAC-SHA1 com o sharedSecret  e o corpo da solicitação.

Aqui está um exemplo de como seria o código de verificação de assinatura se você estiver usando o Node.js (Observação: os detalhes podem diferir dependendo da estrutura que você está usando, da versão do Node em que você está e de outros fatores)

const crypto = require('crypto')

const signatureDigest = crypto.createHmac('sha1', process.env.WEBHOOK_SHARED_SECRET)
  .update(Buffer.from(JSON.stringify(request.body)))
  .digest('hex')

if (request.headers['x-hook-signature'] === signatureDigest) {
  // OK: request came from Reach
} else {
  // Error: request didn't come from Reach
}

Tratamento de erros e novas tentativas

O Reach 360 enviará uma solicitação POST com dados JSON para o configurado targetUrl sempre que uma das configurações events ocorrer. Seu servidor reconhece que recebeu a carga ao enviar de volta uma resposta de 200. Qualquer resposta fora da faixa de 200 indica um erro. Nesse caso, o Reach 360 tentará enviar novamente a solicitação mais 14 vezes nas próximas 48 horas.