Webhooks

We recommend the use of our webhooks to notify API clients of specific events.

These webhooks can only be enabled and updated by a Solutions Engineer.

There are three distinct webhooks available:

• Offer open: indicates when a PrimaryBid Offer has been made live and inbound subscriptions will be accepted for the given offer open time period,
• Offer closed: indicates when a PrimaryBid Offer has been closed and subscriptions will no longer be accepted,
• Allocations available: indicates when PrimaryBid Allocations have been finalised. This webhook will include all allocations at the record level within a single payload or just their total number in the field allocationCount.

URLs

The URLs used for the webhook callback can be a single URL, multiple URLs, or anything in-between (e.g. one for Offers, another for Allocations).

Where common webhook URLs are used, the webhook type will be determined by an HTTP header: primary-bid-event-type. The type will be one of the following:

• offer_open
• offer_closed
• allocation_available

Webhook configuration is defined per user, per environment. For example, a different set of webhook URLs can be set up for different environments (staging or production).

Authentication

PrimaryBid can support the following authentication methods when setting up webhook callbacks:

• OAuth 2.0
• Basic Authentication
• API Keys

The chosen authentication method will be used for all webhook callbacks.

In some cases, different authentication methods can be used for different environments, as we provide Partners with two sets of API client accounts.

Request body

Each PrimaryBid webhook contains a JSON body with an equivalent message received from the response of the respective REST service.

For example, the Offer Open webhook contains the same message response body received when requesting the Get specific offer service.

Here's a code sample:

{
    "id": "63e4d17c735742fee313608f",
    "offerType": "ipo",
    "offerSubType": "investment_trust_ipo",
    "details": {
        "status": "closed_for_subscription",
        "countryCode": "GB",
        "type": "ipo",
        "subType": "primary",
        "estTargetRaise": 1000000000,
        "pressReleaseLink": "",
        "membershipRequired": "no",
        "offeringDocuments": []
    },
    "textProperties": {
        "legalDisclaimer": "Please read our Risk Warning [/risk-warning] before subscribing.",
        "title": "",
        "specialInstruction": "test",
        "companyAnnouncements": "test",
        "priceless": "",
        "useOfProceeds": "test",
        "offerDiscount": null,
        "restriction": "test"
    },
    "issuer": {
        "id": "632d96b32b57bc41a6bc4cb5",
        "businessDescriptionText": "test",
        "companyName": "StagingRegression0802",
        "exchangeMic": "XLON",
        "ticker": "SR",
        "sector": "Automobiles & Parts",
        "securityIdentifier": "GB0032125487",
        "fttRequired": false,
        "sellerName": "",
        "issuerType": "company"
    },
    "dates": {
        "offerStartDateTime": "2023-02-09T11:06:31.926Z",
        "offerEndDateTime": "2023-02-10T10:55:00.000Z",
        "offerEarlyClose": "2023-02-09T11:45:12.660Z",
        "lastModifiedOn": "2023-07-12T15:41:22.651Z",
        "admissionDateTime": "2023-02-10T10:56:00.000Z"
    },
    "pricingAndOrderLimits": {
        "acceptedCurrency": "GBP",
        "priceType": "fixed",
        "offerPrice": 0.01,
        "currency": "GBP",
        "hardMaxLimit": 999999,
        "hardMinLimit": 1,
        "discount": 0,
        "discountTo": null,
        "discountFrom": null
    }
}

Best practice

We allow each Partner to decide if they prefer a single payload webhook for allocations or simply a notification with the allocations count - in this case, they should subsequently poll our:

• GET/allocation endpoint for all allocations, or
• GET/allocation/{offerId} endpoint if you wish to retrieve allocations for a specific offer.

You may now request that PrimaryBid change your WebHook configuration to exclude raw allocation records. The webhook format that includes the allocationsCount field also populates fields such as offerId, price, priceCurrency, securityIdentifier and admissionDateTime.

 {
      "offerId": string,
      "price": number,
      "priceCurrency": [ GBP, EUR, USD ],
      "allocationCount": number,
      "issuer": {
      "securityIdentifier": string
   }
      "dates": {
      "admissionDateTime": ISODate
   }
 }