Assignments (webhook)

Info

The results of asynchronous flinkey-API requests are forwarded by the flinkey backend system via HTTP-POST-Callbacks to webhook endpoints. Affected asynchronous operations are creating, updating and deleting assignments. In order to receive the results of those operations, custom webhook endpoints must be provided. Custom webhook endpoints can be configured in the developer section of the flinkey portal. Here you can also secure your custom webhook endpoint from unauthorized access by providing a secret key. If you choose to enter a secret key and want to process its value, your webhook endpoint must be able to accept requests with a header named 'secret'.

Assignment created

POST

Request parameters

Name	Type	Location	Description
secret	string	header	Optional. Used to secure the webhook endpoint from unauthorized requests. Can be set on the Developer page. If this parameter is set, the according webhook endpoint must be able to accept this header parameter in order to process its value.

Request body

json-schema

{
  "type": "object",
  "properties": {
    "checksum": {
      "type": "string"
    },
    "assignmentId": {
      "type": [
        "number",
        "null"
      ],
      "format": "int32"
    },
    "carId": {
      "type": "number",
      "format": "int32"
    },
    "userId": {
      "type": "number",
      "format": "int32"
    },
    "start": {
      "type": "string",
      "format": "date-time"
    },
    "end": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "customerId": {
      "type": "number",
      "format": "int32"
    },
    "operationSucceeded": {
      "type": "boolean"
    },
    "errorMessage": {
      "type": [
        "string",
        "null"
      ]
    },
    "lifetime": {
      "type": [
        "number",
        "null"
      ],
      "format": "int32"
    },
    "renewableAfter": {
      "type": [
        "number",
        "null"
      ],
      "format": "int32"
    }
  }   
}

checksum

A hash value generated from the payload of the initial request. Serves as a fingerprint to uniquely identify the assignment. Encrypted with the MD5 algorithm. format: A-Z0-9

example - checksum

  12AB34567C8DE9012F3A45BCDE678901

lifetime

An integer based value representing the lifetime of the assignment in seconds. If the value is null, the assignment will have a default lifetime of 604800 (7 days). If not renewed in time, the assignment will become invalid.

renewableAfter

The lifetime of an assignment after which it may be renewed. Attempts to renew assignments earlier will be rejected. Defaults to half of the assignment lifetime lifetime/2.

customerId

An integer based value. It is the ID which is given to a customer by the flinkey backend system.

assignmentId

An integer based value. It is the ID which is given to an assignment by the flinkey backend system. This ID is to be referenced for updating or deleting the assignment.

operationSucceeded

A boolean based value. Set to true if the assignment has been created successfully.

errorMessage

A string based value. It contains the message of the error.

example - errorMessage

  Unable to create assignment. The car for the given car ID has no flinkey Box assigned. ID: {carId}

carId

An integer based value. It is the ID of the car the assignment is issued for.

userId

An integer based value. It is the ID of the user the assignment is issued for.

start

A string based value. It contains the time from when the assignment is valid. format: YYYY-MM-DDTHH:MM:SSZ (24 hour based time)

example - start

  2023-01-31T23:59:01Z

end

A string based value. It contains the time until when the assignment is valid. format: YYYY-MM-DDTHH:MM:SSZ (24 hour based time)

example - end

  2023-01-31T23:59:01Z

Assignment updated

POST

Request parameters

Name	Type	Location	Description
secret	string	header	Optional. Used to secure the webhook endpoint from unauthorized requests. Can be set on the Developer page. If this parameter is set, the according webhook endpoint must be able to accept this header parameter in order to process its value.

Request body

json-schema

{
  "type": "object",
  "properties": {
    "checksum": {
      "type": "string"
    },
    "assignmentId": {
      "type": "number",
      "format": "int32"
    },
    "customerId": {
      "type": "number",
      "format": "int32"
    },
    "operationSucceeded": {
      "type": "boolean"
    },
    "errorMessage": {
      "type": [
        "string",
        "null"
      ]
    },
    "updateData": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "op": {
            "type": "string",
            "enum": [
              "remove",
              "replace"
            ]
          },
          "path": {
            "type": "string",
            "enum": [
              "/carId",
              "/userId",
              "/start",
              "/end",
              "/lifetime",
              "/renewableAfter"
            ]
          },
          "value": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }   
}

checksum

A hash value generated from the payload of the initial request. Serves as a fingerprint to uniquely identify the assignment. Encrypted with the MD5 algorithm. format: A-Z0-9

example - checksum

  12AB34567C8DE9012F3A45BCDE678901

assignmentId

An integer based value. It is the ID which is given to an assignment by the flinkey backend system. This ID is to be referenced for updating or deleting the assignment.

customerId

An integer based value. It is the ID which is given to a customer by the flinkey backend system.

updateData/value

A string based value. It is the XXX format: YYYY-MM-DDTHH:MM:SSZ (24 hour based time)

example - value

  2023-01-31T23:59:01Z

updateData/path

A string based enum value.

example - path

/start

updateData/op

A string based value.

example - op

/replace

operationSucceeded

A boolean based value. Set to true if the assignment has been created successfully.

errorMessage

A string based value. It contains the message of the error.

example - errorMessage

  Unable to find an assignment for the given assignmentId.

Assignment deleted

POST

Request parameters

Name	Type	Location	Description
secret	string	header	Optional. Used to secure the webhook endpoint from unauthorized requests. Can be set on the Developer page. If this parameter is set, the according webhook endpoint must be able to accept this header parameter in order to process its value.

Request body

application/json

{
  "type": "object",
  "properties": {
    "checksum": {
      "type": "string"
    },
    "assignmentId": {
      "type": "number",
      "format": "int32"
    },
    "customerId": {
      "type": "number",
      "format": "int32"
    },
    "operationSucceeded": {
      "type": "boolean"
    },
    "errorMessage": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

checksum

A hash value generated from the payload of the initial request. Serves as a fingerprint to uniquely identify the assignment. Encrypted with the MD5 algorithm. format: A-Z0-9

example - checksum

  12AB34567C8DE9012F3A45BCDE678901

assignmentId

An integer based value. It is the ID which is given to an assignment by the flinkey backend system. This ID is to be referenced for updating or deleting the assignment.

customerId

An integer based value. It is the ID which is given to a customer by the flinkey backend system.

operationSucceeded

A boolean based value. Set to true if the assignment has been created successfully.

errorMessage

A string based value. It contains the message of the error.

example - errorMessage

  Unable to delete assignment. Could not find an customer for ID {customerId}.