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

# Webhook

Webhooks allow external systems to receive notifications when specific events occur in Pactum. Instead of polling the Pactum API for changes affecting entities managed by the integrating system, we will proactively notify you by sending information about the event to a HTTPS endpoint you have defined.

### How It Works <a href="#how-it-works" id="how-it-works"></a>

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2Fdv3SaBLbFsIrE9V1v6ZL%2Fimage.png?alt=media&amp;token=d7080d9c-39bb-4c7d-99e5-dec4cfba1dc8" alt=""><figcaption></figcaption></figure>

### Setting Up Webhooks<br>

1. Implement a HTTPS endpoint to receive webhook events based on our implementation guidelines
2. Notify Pactum to configure the webhook for the workspace(s) you would like to receive messages for

### Event Payload <a href="#event-payload" id="event-payload"></a>

Webhook events are sent as HTTP POST requests with a JSON payload, where the data property value is dependent on the event type. An example in shown below:

`{ "eventId": 436632, "eventType": "NEGOTIATION_EVENT_CONCLUDED", "eventTime": "2025-01-03T10:26:55.412Z", "workspaceId": "123abc", "data": { "id": 17422, "externalId": "PR53496", "externalSystem": "example-system" } }`

#### Payload Fields <a href="#payload-fields" id="payload-fields"></a>

| Field         | Type   | Description                                             |
| ------------- | ------ | ------------------------------------------------------- |
| `eventId`     | number | Unique identifier for the webhook event                 |
| `eventType`   | string | Type of the event (e.g., `NEGOTIATION_EVENT_CONCLUDED`) |
| `eventTime`   | number | ISO timestamp when the event occurred                   |
| `workspaceId` | string | ID of the workspace where the event occurred            |
| `data`        | object | Event-specific data payload                             |

#### Event specific data payloads <a href="#event-specific-data-payloads" id="event-specific-data-payloads"></a>

**NEGOTIATION\_EVENT\_CONCLUDED**

| Field            | Type           | Description                                                                             |
| ---------------- | -------------- | --------------------------------------------------------------------------------------- |
| `id`             | number         | Unique identifier for the Negotiation Event in Pactum                                   |
| `externalId`     | string         | External ID identifying the entity in the origin system                                 |
| `externalSystem` | string \| null | Optional: Additional information about the system the negotiation event originated from |

### Handling incoming webhooks <a href="#handling-incoming-webhooks" id="handling-incoming-webhooks"></a>

Implementors are advised to follow these guidelines in their webhook event handlers:

1. The incoming requests should be verified, as coming from Pactum, using the signature based authentication mechanism detailed in the Authentication section
2. The event should then be processed based on the `eventType`. Although Pactum will currently only deliver`NEGOTIATION_EVENT_CONCLUDED` events, the set of events may grow over time. As such implementors are required to **explicitly check** the `eventType` value before proceeding to process the contents of the `data` property.
   1. Certain events, such as `NEGOTIATION_EVENT_CONCLUDED`, include further information (such as `externalId` and `externalSystem`) to determine whether the event is relevant for the webhook receiver. Implementors are advised to acknowledge events, which are irrelevant for the receiving endpoint, by also responding with a 2xx response. Responding with an error code will result in event delivery being retried in accordance with the retry policy outlined in the Retry Policy section of this document
3. The receiving endpoint must return a 2XX HTTP status code in 10 seconds to acknowledge receipt. Pactum will otherwise continue to attempt delivery as outlined in the Retry Policy section. Implementors are currently advised to respond with a 2XX HTTP status codes in all cases where delivery should no longer be attempted (e.g. `eventType` not supported by the endpoint) to avoid unnecessary delivery attempt&#x73;**.**

The below sequence diagram outlines the expected process upon receiving a webhook event from Pactum:

<figure><img src="https://2769938103-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FM7KTpbu7nDWmneLhlf%2Fuploads%2FPJEw1mKA95FKmTslFVmH%2Fimage.png?alt=media&amp;token=0ade4bc2-e11c-4d4c-a292-af07d86a44e1" alt=""><figcaption></figcaption></figure>

### Authentication <a href="#authentication" id="authentication"></a>

Each webhook request is signed using a JWT-based signature mechanism to ensure authenticity and integrity of the messages. The signature is included in the `Pactum-Signature-V1` header.

#### Validating Webhook Requests <a href="#validating-webhook-requests" id="validating-webhook-requests"></a>

To validate incoming webhooks, follow these steps:

1. **Retrieve Public Keys**

   * Periodically fetch the active public keys from our [JWKS](https://www.jbspeakr.cc/jwks-json-web-key-set/) endpoint
   * Cache these keys for subsequent verifications

   `GET /.well-known/jwks.json`
2. **Verify the Signature**
   * Extract the JWT from the `Pactum-Signature-V1` header
   * Verify the JWT using the public key matching the `kid` in the JWT header
   * If the `kid` is unknown, refresh your cached keys
3. **Validate Claims**
   * Check the `exp` (expiration) claim hasn't passed
     * Note: most JWT verification libraries perform this check during signature validation
   * Compute SHA-256 hash of the raw webhook payload
   * Verify it matches the hash contained in the `messageDigest` claim in the JWT

Example JWT Payload:

`{ "exp": 1704495360, // Expiration timestamp "messageDigest": "sha-256=:base64encodedstring:" }`

### Retry Policy <a href="#retry-policy" id="retry-policy"></a>

If your endpoint returns a non-2XX response or times out in 10 seconds, we will retry the delivery:

* Retries continue for up to 24 hours
* Retry uses exponential backoff between attempts
* After 24 hours, undelivered events are discarded

### Processing only a subset of relevant events <a href="#addendum-processing-only-a-subset-of-relevant-events" id="addendum-processing-only-a-subset-of-relevant-events"></a>

The Pactum webhook delivery system is generic and as such will deliver notifications about all negotiation events within workspaces an endpoint has been subscribed to. The receiving endpoints are expected to be able to determine whether a notification is relevant for their implementation and acknowledge (without processing) any irrelevant notifications.

In order to achieve this we advise the following approaches:

* `eventType` - the event type must be explicitly checked before processing the contents of the `data` property. When an unexpected event type is encountered the receiving endpoint should acknowledge receipt while ignoring the event.

In case of a `NEGOTIATION_EVENT_CONCLUDED` event:

* `externalId` - Entity reference identifier provided during negotiation event creation
* `externalSystem` - Originating system identifier provided during negotiation event creation

These two fields are expected to be provided by the calling system and are treated as free text by Pactum. They will be provided, unedited, in both the webhook and API response payloads to allow for cross referencing with entities in originating systems. As such when the integrating system is also responsible for creating negotiation events in Pactum, then it should provide an unique `externalSystem` value in addition to the `externalId` to allow for filtering during webhook event receipt.
