This guide is an overview of information related to syncing users to your 7Geese organization using Webhooks. Webhooks provide an alternative to syncing user data when that data might not be available over the internet. Setting up an HRIS Webhook Integration requires technical work on your end to send data from your HRIS system to 7Geese. This guide will cover:

  • Creating a webhook
  • Testing your webhook
  • Enabling your webhook

Creating a Webhook

In the integrations section of 7Geese, click Configure next to "HRIS Webhook".

After picking your Sync Type and configuring which fields you want to sync, click the Create Webhook button.

You should be provided with an API Key and a Webhook Endpoint. Make a note of these values as you will need it to send data to 7Geese.

Testing your Webhook

When you first create a new HRIS Webhook, it is created in Test Mode.

Test mode allows you to send data to your Webhook Endpoint without it affecting any of your data in 7Geese. You can run a simulation with the data you submitted to see how a particular webhook request would have affected users in your organization. You can view all the requests you have made to your Webhook Endpoint and run simulations from the HRIS Webhooks Logs page: https://app.7geese.com/admin/hriswebhook/logs/

Sending Data to 7Geese

To send data to 7Geese, you have to POST JSON data to your Webhook Endpoint and send your API Key in the X-HRIS-AUTHENTICATION header of the request.

The data you send to 7Geese needs to be structured in a specific way. This JSON schema describes how to structure your data before sending it to 7Geese.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "hris_id": {
            "type": "string",
            "description": "An ID that uniquely identifies the user within your HRIS. You may also set this to the email address of the user if you don't have an HRIS ID available."
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "email": {
            "type": "email"
          },
          "job_title": {
            "type": "string"
          },
          "phone_number": {
            "type": "string"
          },
          "employee_id": {
            "type": "string"
          },
          "hire_date": {
            "type": "string"
          },
          "profile_image": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "last_modified": {
                "type": "date-time"
              },
              "cache_info": {
                "type": "string"
              }
            },
            "required": [
              "url"
            ]
          },
          "departments": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "For sub-departments, use > to indicate the department is inside a larger department. Eg 'Engineering > Mobile Team'\n\n\nNew Departments:\n\nIf a department does not exist in 7Geese, it will be created."
            }
          },
          "active": {
            "type": "boolean"
          },
          "manager": {
            "type": "object",
            "properties": {
              "hris_id": {
                "type": "string"
              }
            },
            "required": [
              "hris_id"
            ]
          }
        },
        "required": [
          "active",
          "email",
          "hris_id",
          "first_name",
          "last_name"
        ]
      }
    }
  },
  "required": [
    "users"
  ]
}

Note that not all fields are required. Here is a complete example of data structured in the correct way. 

{
  "users": [
    {
      "hris_id": "1FdzdQf35CffSd53",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@7geese.com",
      "job_title": "VP Engineering",
      "phone_number": "+1 223-334-4355",
      "employee_id": "E123556",
      "hire_date": "2016-10-25",
      "profile_image": {
        "url": "https://s3.amazonaws.com/publicassets.7geese.com/misc/765-default-avatar.png",
        "last_modified": 23323123123123,
        "cache_info": "sadsaDSds343GzzZ"
      },
      "departments": [
        "Engineering > Mobile Team",
        "Customer Success > Support > Mobile Support",
        "Sales > Sales Engineer"
      ],
      "active": true,
      "manager": {
        "hris_id": "E9923443"
      }
    }
  ]
}

Here is an example of sending valid data to your Webhook endpoint using cURL. Assuming you stored the above example data as webhook-data-example.json, run:

curl --header "X-HRIS-AUTHENTICATION: 773603159c636db69c1e596c68a6368624305bcb" \
     --header "Content-Type: application/json" \
     -X POST \
     --data-binary '@webhook-data-example.json'  \
     https://app.7geese.com/hriswebhook/sync/e4a777a9021349fc9d061bd60fe1ec20/

Enabling your Webhook

After enabling your webhook, any data sent to your Webhook Endpoint will be actively synced with 7Geese. To enable your Webhook, check the Enable webhook checkbox and click the Save Settings button on the integration page. 

At any time you can disable or update your webhook. Updating puts the webhook back in Test Mode. You should test your integration again after modifying it before activating the webhook again.

Did this answer your question?