Connection setup

The first part of the implementation is the setup of the connection. Your customer needs to generate and share their API credentials so that we can make the necessary API calls for the integration.

There are multiple ways of implementing this step, but during your development and for the first customers we highly recommend just using the Magic Link feature that we provide. This guide will therefore assume that you are using the magic links for setting up the connection.

1. Generate a link for your customer. You only have to go into the dashboard and:

   • Click on New integration

   • Click on “Let your customer create the integration” (during development, you can also use the first option).

   • Click on “Continue”.

   • Copy the link.

2. Wait for your customer to generate and enter their API credentials. You can see the status of any sent-out connection link in the Kombo dashboard.

   🦉 Setting up the credentials for an integration can be tricky for your non-technical users. That’s why we highly recommend sharing our step-by-step connection guides with them or guiding them through the process on a short call.

3. Receive the integration-created webhook. We send this webhook every time one of your customers creates a new integration.

   {
     "id": "5gjAtURLPbnTiwgkaBfiA3WJ",
     "type": "integration-created",
     "data": {
       "id": "personio:CBNMt7dSNCzBdnRTx87dev4E",
       "tool": "personio",
       "category": "HRIS",
       "end_user": {
         "origin_id": "36123",
         "creator_email": "user@example.com",
         "organization_name": "Acme, Inc."
       }
     }
   }
   

   The end_user.origin_id is submitted by you when creating a connection link and should represent the ID of your customer in your database. You need to store this ID in your database so that you’ll know which HRIS system belongs to which customer. For example, if you have two customers with the IDs “42” and “43”, then your database could look as follows after the integrations have been created:

   end_user.origin_id	kombo_integration_id
   42	personio:8d1hpPsbjxUkoCoa1veLZGe5
   43	successfactors:B1hu5NGyhdjSq5X3hxEz4bAN

   ⚠️ This ID is not for public display and should only be accessible to your backend. The ID is not a secret as such but it’s one of two things needed alongside the API key. There is no way to list all integration IDs via the API key so even in the case of an accidental API key leak, the data would still be safe.

Alerting for customer problems

We will send you a connection-flow-failed webhook every time a customer is running into an issue. You should set up some sort of alerting based on this webhook so that you can be fast to offer help to your customer, should they have an error when setting up an integration.

{
  "id": "5gjAtURLPbnTiwgkaBfiA3WJ",
  "type": "connection-flow-failed",
  "data": {
    "integration_tool": "personio",
    "integration_category": "HRIS",
    "end_user": {
      "origin_id": "36123",
      "creator_email": "user@example.com",
      "organization_name": "Acme, Inc."
    },
    "log_url": "https://app.kombo.dev/env/production/logs/C3xUo6XAsB2sbKC7M1gyXaRX"
  }
}

Handling deleted integrations

It is of course also possible to delete integrations. This can be done in two ways:

• via the “delete integration”-endpoint. If you are calling this endpoint you should also take care of deleting the kombo_integration_id from your database.

• via the integration-deleted webhook. This will be sent to you if someone goes into the Kombo dashboard and deletes an integration manually. Also then you’ll have to remove the kombo_integration_id from your database.

  {
    "id": "5gjAtURLPbnTiwgkaBfiA3WJ",
    "type": "integration-deleted",
    "data": {
      "id": "personio:CBNMt7dSNCzBdnRTx87dev4E",
      "tool": "personio",
      "category": "HRIS",
      "end_user": {
        "origin_id": "36123",
        "creator_email": "user@example.com",
        "organization_name": "Acme, Inc."
      },
      "deleted_at": "2022-11-02T10:50:10.242Z"
    }
  }