Guides
Data PrivacyImprint

Webhook Setup

Set up a Webhook to be notified about events as they occur.

Suggest Edits

The lemon.markets brokerage platform provides a ReSTful API to provide an API matching the imperative programming paradigm. In order to enable event-driven models, we also provide a notification mechanism using Webhooks. This provides our partners with the capability to react to events occurring within the brokerage platform, e.g. sending a push notification after executing an order.

Register a Webhook

In order to register a Webhook with the brokerage platform, a request is sent to the endpoint POST /v1/webhooks. For this sample, we visit webhook.site and generate a new webhook: https://webhook.site/48cf1291-4ab5-452b-9d07-17103ab8e768

Now we can send this request body to POST /v1/webhooks (remember to use your API key and the data privacy headers):

{
  "url": "https://webhook.site/48cf1291-4ab5-452b-9d07-17103ab8e768",
  "events": [
    "account.created"
  ]
}

You should receive an HTTP response with status 201 Created:

{
  "events": [
    "account.created"
  ],
  "id": "wbh_68747470733a2f2f6c656d6f6e2e6d73",
  "signature_secret": "f09f8d8b2068747470733a2f2f6a6f62732e6c656d6f6e2e6d61726b6574732f",
  "url": "https://webhook.site/48cf1291-4ab5-452b-9d07-17103ab8e768"
}

This provides us with an identifier for the webhook and a signature secret. That identifier can be used to eventually remove a registered webhook, the signature secret can be used to authenticate incoming Webhook messages (we’ll dive into these details later).

Trigger the Webhook

After configuring the Webhook, we can now perform an action on the API. Creating a new account will result in a notification. So we perform a call like this:

# curl -X POST \
    https://sandbox.api.lemon.markets/v1/accounts \
    -H 'Content-Type: application/json; charset=utf8' \
    -H 'Authorization: Bearer <your-api-key>' \
    -H 'LMG-Data-Privacy-Access-Principal: nobody' \
    -H 'LMG-Data-Privacy-Access-Justification: webhook-test' \
    --data-binary '
    {
      "accepted_agreements": [
		    {
		      "accepted_at": "2023-06-29T14:39:29Z",
		      "agreement_id": "agr_9902271f791d413aad781763c61b9bb0"
		    },
		    {
		      "accepted_at": "2023-06-29T14:39:29Z",
		      "agreement_id": "agr_8ec894e1ec764a339e172292dff9aeff"
		    }
		  ],
		  "declaration_of_acting_on_own_account": true,
		  "customer": {
		    "date_of_birth": "1964-08-13",
		    "email": "[email protected]",
		    "employment": {
		      "annual_salary": "gte_50k_lt_75k_eur",
		      "sector": "public_sector",
		      "status": "employed"
		    },
		    "firstname": "Erika",
		    "gender": "female",
		    "lastname": "Mustermann",
		    "marital_status": "married",
		    "nationalities": [
		      "DE"
		    ],
		    "phone_number": "+49172997318",
		    "place_of_birth": {
		      "city": "Berlin",
		      "country": "DE"
		    },
		    "registered_address": {
		      "city": "Köln",
		      "country": "DE",
		      "line_1": "Heidestraße 17",
		      "postal_code": "51147"
		    },
		    "tax_residencies": [
		      {
		        "country": "DE",
		        "tax_identification_number": "123/456/78901"
		      }
		    ]
		  }
    }
    '

After receiving an HTTP status of 200 OK, we can browse the webhook results at https://webhook.site/#!/48cf1291-4ab5-452b-9d07-17103ab8e768

You’ll see that the lemon.markets platform has issued a POST request to the webhook with the following payload:

{
  "id": "evt_a8b11a37eccc49ecacb372e3a92a184d",
  "type": "account.created",
  "created_at": "2023-06-29T14:40:30.523373+00:00",
  "context": {
    "account": "cusa_33531f7f801d4ce997747470ab7208fd"
  }
}

This payload matches for format of events you’ll find at /v1/events.

Conclusion

Now you’re familiar with the steps involved in setting up WebHooks. This will provide you with an efficient way to react to events as they happen.

References

Updated 6 months ago