You can receive document data from d.velop invoices for further processing in two ways: via webhook or via the API for retrieving outstanding transfers. If you choose to process the data via a webhook, d.velop invoices calls your implemented web service with the data of the document to be transferred. If you process the data by retrieving the transfers, your application is responsible for the regular retrieval of the outstanding documents within a configurable time frame, processing them and reporting whether or not processing was successful to d.velop invoices.

When is a webhook the better option and when is retrieval via API? 

The retrieval of data via API and receipt of the data via webhook basically offer the same scope of functions. You get the same document data with both variants, and both variants require you to report whether or not processing was completed. So when should you choose to retrieve the data via API and when should you choose to receive it via webhook?

A webhook lets you respond to document data more quickly, because d.velop invoices actively contacts your application as soon as there is data to be processed. You can immediately check the data for validity and provide a reply, for instance. If you retrieve the data via API, your application checks whether new data is available at regular intervals. If this check is performed once an hour, for example, your application only transfers data to the external system once an hour as well. If errors occur and you report the process to be unsuccessful, the users only find out about this with this delay too.

To retrieve document data via API, your application must be able to access the d.velop invoices API. If you are using the cloud version of d.velop invoices, your application must therefore have internet access. To ensure that you can receive data via a webhook, d.velop invoices must be able to reach your application. If you are using the cloud version of d.velop invoices, your application must be accessible from the internet.

Format of the document data 

Both methods deliver the document data to you in a standardized format.

{
  "event_type": "integration.export",
  "_links": {
    "dmsobject": {
      "href": "https://example.d-velop.cloud/dms/r/21b9b52f-19e3-4b3d-8ac6-b32d991f83e0/o2/P000000001"
    }
  },
  "workflow": {
    "voucher": {
      "doc_id": "P000000001",
      "company": {
        "nr": "01",
        "name": "docures AG"
      },
      "vendor": {
        "nr": "50001",
        "name": "Schrauben Meier GmbH"
      },
      "vendor_bank_account":  {
        "id":  "",
       "iban":  ""
      },
      "currency": {
        "id": "EUR",
        "name": "Euro",
        "code": "EUR"
      },
      "net_amount": 100.0,
      "gross_amount": 119.0,
      "pay_amount":  null,
      "vat_amount": 19.0,
      "document_date": "2020-05-05T00:00:00+00:00",
      "internal_number": "INT010291",
      "external_number": "INV12310",
      "payment_date": "2020-05-10T00:00:00+00:00",
      "date_of_supply": "2020-05-05T00:00:00+00:00"
      "financially_correct":  false,
      "document_type": {
        "id": "inv",
        "name": "Invoice",
        "credit_note": false
      },
      "payment_terms": {
        "id": "NET30",
        "net_days": 30,
        "cashback_days1": 10,
        "cashback_percentage1": 2.5
      },
      "posting_period": "2020-05-09",
      "posting_date":  "2020-05-09T00:00:00+00:00",
      "posting_text": "M3x3mm screws",
      "barcode": "BC1234",
      "custom1": "Sales"
      "line_items": {
        "5afe1329-83cd-4ccc-b806-f9ee458522b7": {
          "internal_id": "5afe1329-83cd-4ccc-b806-f9ee458522b7",
          "line_no": 1,
          "verified": true,
          "verifier": {
            "type": "user",
            "name": "mmus",
            "display_name": "Max Mustermann"
          },
          "verified_by": {
            "type": "user",
            "id": "257659",
            "name": "mmus",
            "display_name": "Max Mustermann"
          },
          "verified_at": "2020-05-05T10:25:00+01:00",
          "gl_account": {
            "nr": "6300"
          },
          "cost_center": {
            "nr": "1000"
          },
          "cost_unit": {
            "nr": "PJ0001"
          },
          "net_amount": 100.0,
          "gross_amount": 119.0,
          "pay_amount": null,
          "vat_amount": 19.0,
          "tax_code": {
            "id": "DE_S",
            "name": "Vorsteuer 19%",
            "percentage": 19.0
          },
          "order_number": "PO001",
          "order_line": 1,
          "order_id": "PO_001",
          "order_line_id": "PO_001_1",
          "quantity": {
            "invoiced": 2
          },
          "unit": "Pcs.",
          "unit_price": 50.0,
          "description": "Schraubendreher",
          "item_number": "4711",
          "discount_absolute": 0,
          "discount_per_unit": 0,
          "discount_percent": 0,
          "discount2_percent": 0,
          "discount3_percent": 0,
          "discount4_percent": 0,
          "discount5_percent": 0,
          "custom1": "Neubau"
        }
      }
    },
    "step": {
      "id": "64576949-ff8e-4e45-b0ec-7b4e25436331",
      "title": "Verification"
    }
  },
  "connection": {
    "from_step": {
      "id": "9080a8d4-6698-4613-b5c1-6c1ca103daab",
      "title": "Verification"
    },
    "to_step": {
      "id": "fd51ab72-aceb-4c1d-b775-ea3d411c9284",
      "title": "Approval"
    },
    "end_mode": null
  }
}

At the highest level, you receive the following data:

Information about the step connection 

An export (event type integration.export) is always triggered in the context of a connection between two workflow steps. This information helps you to determine, for example, whether the workflow ends with the transfer.

Information about the current workflow status (workflow object) 

Document header data (voucher object) 

All the document header data is grouped together in this object.

Information about document line items (line item object) 

Each individual document line item supports the following properties:

Receiving data via webhook 

You can use webhooks to receive document data from d.velop smart invoice in an external system via HTTP. To do so, you can use an integrating application where you store an HTTP endpoint.

What are webhooks? 

d.velop smart invoice can use webhooks to inform an external application (such as an ERP system, for example) when certain events occur. The external application can then respond to this event, for example, by generating a posting proposal.

From a technical perspective, a webhook can be created in any kind of technology as long as the application provides an HTTP endpoint that can receive POST requests in a format specified by d.velop smart invoice.

Implementing a webhook endpoint 

To implement a webhook endpoint, you must first make a new endpoint available in your application. The way to do so depends on the technology that you are using: for example, it may be a new .php file in a PHP application or a new route in Microsoft ASP.NET MVC.

The endpoint is then tasked with extracting and processing the JSON from the POST request. At the end of processing, you must return an HTTP status code that indicates whether processing was successful to d.velop smart invoice.

The data that d.velop smart invoice sends to the endpoint corresponds to the event object from the API.

You should also authenticate the incoming requests to ensure that they actually originate from d.velop smart invoice.

Status codes and return values 

If you were able to process the webhook request correctly, you should respond with HTTP status code 200. If errors occurred, you should respond with status code 500 if there is a program error on your side.

If the cause was invalid information (for example, a G/L account that did not exist), you should respond with error 400. In this case, you can also enter an error message in the response. This error message is displayed for the user in d.velop smart invoice. You must enter the error message in German and English.

For example:

{
  "error": {
    "de": "Die Buchungsperiode wurde bereits geschlossen.",
    "en": "The posting period has already been closed."
  }
}

Authenticating requests 

When you implement a webhook endpoint, you must ensure that incoming requests actually originate from d.velop smart invoice. For this purpose, each request includes a signature in the header X-Smart-Invoice-Signature. To verify the signature, you require the secret from the webhook integration settings. The secret differs in each integrating application.

The header X-Smart-Invoice-Signature contains the signature and a timestamp. This timestamp is specified as a Unix timestamp in the key t. You can find the signature in the key v1.

X-Smart-Invoice-Signature: t=12839891289,v1=38941389418903890128930jaskldjl221

The signature is generated by d.velop smart invoice in accordance with the HMAC-SHA256 method. To check the signature, proceed as follows:

GET /smartinvoice/api/v1/transfers?integration_key=abc
Accept: application/json

{
  "_links": {
    "next": {
      "href": "https://test.d-velop.cloud/smartinvoice/api/v1/transfers/..."
    },
    "previous": {
      "href": "https://test.d-velop.cloud/smartinvoice/api/v1/transfers/..."
    },
  },
  "transfers": [
    {
      "_links": { ... },
      "workflow": {
        ...
      }
    }
  ]
}

POST /smartinvoice/api/v1/transfers/:id
Content-Type: application/json

{
  "successful": false,
  "error": {
    "de": "Transfer fehlgeschlagen.",
    "en": "Transfer failed."
  }
}