Event Subscription Service v4

The Event Subscription Service (ESS) implements the Publish/Subscribe pattern using principles of Event Driven Architecture in the SAP Concur platform. It allows clients and partners to be notified through web services when certain actions take place in connected companies. When the business/system event occurs ESS sends that event to the configured endpoint with relevant information.

  • Event - a state of a business/system object or entity. Always has an EventType that represents a type of entity change or specific state in a workflow. Example: StatusChanged, etc.
  • Topic - a stream of events of business/system object or entity. Example: public.concur.expense.report, public.concur.travel.request.
  • Subscription - a topic consumer. Each subscription has a topic it is subscribed to.
  • Webhook - an ESS application that uses a subscription model and delivers events to the endpoint.

In order to begin receiving events, you must first subscribe to the relevant topic(s) for your application. To subscribe to an event, you must work with your relevant SAP Concur technical contact; for partners, please work with your technical enablement contact. For customers, your web services consultant will subscribe on your behalf to the relevant topic(s).

Limitations

Access to this documentation does not provide access to the API.

Scope Usage

There are two levels of scopes required for creating subscription.

Name Description Endpoint
events.topic.read Access to ESS API GET, POST, PUT, DELETE
%topic scope% Access to specific topic (events) GET, POST, PUT, DELETE
  • If application has only the events.topic.read scope an empty list of topics will always be returned.
  • See the Event Topics section for the various Topics and corresponding required scope(s).

Process Flow

Process flow for ESS

Access Control

ESS requires a caller to have a proper JWT and scopes, for more details please see the Scopes documentation. A caller must have the following types of scopes:

  • The ESS API level scope events.topic.read is required to be able to access ESS API.
  • A resource level scope, for example expense.report.read is required to be able to access the public.concur.expense.request topic and to be able to create subscriptions to that topic.

All required scopes can be requested for a caller application by Partner Enablement team.

ESS Delivery Model

It is important to remember that ESS doesn’t have an API that you can call for events, ESS delivers events to your endpoint.

  • It uses an outbound callout where the SAP Concur offering calls a public facing URL provided by client or partner, which is a web server hosted by the third-party developer or client.
  • The application endpoint can also use the related web services to retrieve or send SAP Concur data. For example, an event may be generated when a request for travel is submitted. The application endpoint may then leverage data from the event, such as the request ID, to retrieve the relevant travel request record from the published Request APIs.

Endpoint Requirements

ESS guarantees at least once event delivery. This is accomplished through the retry posting the event payload to the subscribers’ endpoint until the response indicates successful receipt. The expected maximum acknowledgment time for a request to the subscribers’ endpoint is 30 seconds. The service will attempt posting to the endpoint and then hold and retry until the subscriber endpoint responds with delivered or not accepted. The service will retry at least 3 days and skip to the next event after unsuccessful delivery.  We suggest that the subscriber consider following:

  • Endpoint response time requirements depend on the topic throughput. Please review the topic documentation for throughput.
  • It is highly recommended to implement a queue behind the subscriber’ endpoint in order to keep response time as low as possible.
  • The subscriber must maintain a reasonable uptime to support the requirements of the integration scenario.
  • Your HTTPS server endpoint must be accessible from the public web with a non-self-signed certificate.  The certificate should be signed by a known Certificate Authority and should be reachable through DNS.

ESS Authentication

We strongly recommend you use the certificate Common Name as the authentication mechanism to ensure your endpoint is accessed by our service. We will always use the same client x509 certificate (until Oct 22, 2024 it will be Expiring x509 certificate). The common name is C=US, ST=Washington, L=Bellevue, O=Concur Technologies, Inc., CN=webhook.api.concursolutions.com and the certificate serial number is 015867318CAA347FBC6288C29E9CB35B (until Oct 22, 2024 it will be 0804AA16E0BAAD2B86F75421A13FCC68)

If you decide not to follow that approach and rely on the certificate Serial Number or the certificate itself, please be aware that every year when the certificate will be re-issued and you have to update your authentication mechanisms.

We will always use a digital signature, supplied in the request header Concur-Signature. If you decide to use this authentication method you will need our Public Key.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2wJd8TVDGUxD00bCqemz
cptSfm7VGNa8Bm2DIpmqobzN6jv/HNzI3HPjeqcP1GtA4vjoFkFRaW2Qs286cI7e
9GcLbJP4mzww97LfbZYGTI+9SAlxDKEZl/AWbwTi6P8lOxho8fQ4Sv4eSK7hyL3l
I82XdBYJ2JWRpEQ1hZOui1f0BlFyqFVrEbzolE6S0eeP3gb1szFELz8ES5T4/T0o
Tz1KZE2knMsugAz760Mlmc7EuLutnNhfCZQypNUZ9fI2CMSZWHZa8IH9MCz/ywuE
NYp3hlsu0Q+oYeAwpDKyoWNLcV8pKaStVnP+3yn+/J3/oK4Rtqz/lKRrepxwTVRA
1wIDAQAB
-----END PUBLIC KEY-----

ESS Behavior

The Event Subscription service has the following characteristics from the subscriber perspective:

  • Requests will come from us.api.concursolutions.com, emea.api.concursolutions.com, or cn.api.concursolutions.com.
  • Connection will always be established using a mutual TLS with webhook.api.concursolutions.com x509 certificate.
  • Requests will always have a digital signature.
  • Requests will be re-tried when the subscriber responds with HTTP Response Code(s): 5xx, 401, 403, or 429.
  • Requests will not be re-tried when subscriber responds with HTTP Response Code(s):
    • 2xx – Indicates successful receipt of the event.
    • 4xx – Indicates posted event is unexpected or incorrectly formatted.
  • Request will be retried until delivery OR event retention period expiration.
  • Event retention period is 72 hours from the time of event being published.
  • Events are not archived, but all of the event delivery attempts/responses are logged and retained for 30 days.

ESS Resourse usage

Every ESS subscription is a separate application with dedicated resources. In order to make sure that resources are used efficiently we have several limitations and guidelines.

  • Each application can have up to 5 subscriptions.
  • Subscriptions that are not working properly will be deleted after 30 days. This includes unused subscriptions with incomplete setup (missing company ids) and subscriptions with no successful deliveries due to endpoint errors.
  • When creating a new subscription please choose a name that reflects the subscription purpose or workflow, eg. test, prod, etc.
  • Please make sure you delete your unused subscriptions created for testing purposes after testing is complete.

On this page