> For the complete documentation index, see [llms.txt](https://developer.usemultiplier.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.usemultiplier.com/webhook-integration-dump.md).

# Webhook Integration-dump

The Webhook integration allows partners to be notified of various changes happening on Multiplier side.

## Initial setup

1. Partners must inform Multiplier of their webhook URL
   1. Example: `https://xyz.partner-name.com/webhook`
2. Once setup, all Multiplier events are fired to the above URL.
3. The partner can filter by event types (see below) as to what events they deem interesting.

## Webhook content

Multiplier will send `POST` requests to the partner’s webhook URL with the following content (the content is additionally **signed**):

```json
{
	"eventType": "String",
	"data": Object
}
```

The `content-type` header is `application/json` .

The `data` object varies based on the event type; see content below.

As the webhook is **signed** you will not receive the raw JSON as above but a JWS string like this:

```json
eyJraWQiOiJ0ZXN0LWtleS1pZCIsImFsZyI6IkVTNTEyIn0.eyJldmVudFR5cGUiOiJDT05UUkFDVF9BQ1RJVkFURUQiLCJkYXRhIjp7ImN1c3RvbWVySWQiOiI0MTk5ZmE5MC1iNjM3LTQ5YWYtYTAyNS00NmE3MTMzODFlYTEiLCJjb250cmFjdElkIjoiZWNkMzQzNzUtYTk5NS00YjhkLThmZTItN2Y3NWU3N2E0YjUwIiwic3RhdHVzIjoiQUNUSVZFIiwidHlwZSI6IkVNUExPWUVFIiwiY291bnRyeSI6IlVTQSJ9fQ.AOVHvnFH3VGRy9YedX2XNFeUSYf7prrhZrp6CeI-RM_dmkrDROvtUPUiQLcXth7tPuX61PVhtgwYg81PRpItjTRmAW2jzIxBi5lThZRCvL7L8eQdPprsigT2_HW0ehCee3xfG4fORhlH4wLLtDBm4c7T1YWbQqz15X7SzYQ6fGBCvS-B
```

To view the (unverified!) content you can use tools like <https://www.jwt.io/>

## How to validate received data?

To ensure the content is indeed sent by Multiplier you must verify the signature of the received data. For this you must fetch the Multiplier public key set (JWKS) matching the private key used for signing the JWS. You can retrieve it like so:

```json
curl --location '<https://api.usemultiplier.com/v1/partner/.well-known/jwks.json>'
```

**Note:** The keys in this key-set can be rotated without prior communication; you may cache this response up to **1 hour** but after that you must re-fetch the set. As long as any one key in the key-set matches the JWS you can continue as authorized.

A JWKS might look like this:

```json
{
  "keys" : [ {
    "kty" : "EC",
    "crv" : "P-521",
    "kid" : "strategic-partner-service-key",
    "x" : "ATGYQ3Swxio2PULu8cHU5m0DrEodcPHplzBDZLsG9NiiiWuJDsU1giwRISaMTJxtJThw8vhLDNQSK0mVXjRX947l",
    "y" : "AItDCJC1319jdVh86cVJLSu98HvLOPJdH23WScSMOsivkHl5EdUv7PMjH3OF7-dDbmZN-LuWM86aXh7JHMWGZGww",
    "alg" : "ES512"
  } ]
}
```

This is a sample implementation in Kotlin:

```json
import com.nimbusds.jose.JWSObject
import com.nimbusds.jose.jwk.ECKey
import com.nimbusds.jose.jwk.JWKSet
import com.nimbusds.jose.crypto.ECDSAVerifier

import com.fasterxml.jackson.databind.ObjectMapper

// Parse the JWKS, which contains the public keys for verification
val jwkSet = JWKSet.parse(<JWKS String as per JWKS endpoint>)
// Retrieve the right public key from the JWKS
val publicKey = jwkSet.getKeyByKeyId(jwsObject.header.keyID) as ECKey
// Initialize your verifier
val verifier = ECDSAVerifier(publicKey)
// Parse the raw signed payload
val jwsObject = JWSObject.parse(signedPayload)

// Verifiy the payload. This is the vital step!
if (!jwsObject.verify(verifier)) {
	throw RuntimeException("Verification failed!")
}

// Read the data
val payloadJson = objectMapper.readTree(jwsObject.payload.toString())
val eventType = payloadJson.get("eventType").asText()
val customerId = payloadJson.get("data").get("customerId").asText()
```

## List of event types & their content

* `*CONTRACT_ACTIVATED`\*

  * Fired when an employee’s contract is moved to `active` state.
  * Data:

  ```json
  {
  	"contractId": UUID,
  	"customerId": UUID,
  	"status": "ACTIVE",
  	"type": "EMPLOYEE", "HR_MEMBER", "FREELANCER", or "CONTRACTOR"
  	"country": 3-letter ISO code, e.g. "USA"
  }
  ```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.usemultiplier.com/webhook-integration-dump.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.