Prescription Notification Webhooks

Osigu provides webhook notifications for prescription events, enabling real-time updates on prescriptions' status through different stages. These webhooks are triggered automatically and require the client to provide a REST endpoint capable of receiving POST requests.

Events Overview

The following events are available:

Webhook Configuration

To use these webhooks, you must provide Osigu with two REST endpoints—one for sandbox (testing) and one for production—both secured via HTTPS.

Requirements

1. Protocol: Endpoints must use HTTPS.
2. Authentication: Authentication is required via a custom header and HMAC-based signature validation.

Authentication and Signature Validation

For enhanced security, Osigu will include a custom header for authentication (X-Api-Key) and a signature for payload validation (X-Signature). These measures ensure that requests are authentic and unaltered.

Authentication Header

• Header Name: X-Api-Key
• Value: Client-provided API token.

Signature Validation

Osigu will include an X-Signature header in the webhook request. This signature is generated using the HMAC SHA-256 algorithm with a pre-shared secret key provided during the integration process.

To validate the signature:

1. Compute the HMAC SHA-256 hash of the request body using the shared secret.
2. Compare the computed hash with the value of the X-Signature header.

Example in pseudocode:

computed_signature = HMAC_SHA256(secret_key, request_body)
if computed_signature != X-Signature:
    reject_request()

Failure to validate the signature should result in rejecting the request with an appropriate HTTP 401 response.

Webhook Payload

Osigu sends notifications using a POST request with a JSON body. The payload includes the following attributes:

Response Expectations

Successful Processing (HTTP 204)

The endpoint should return 204 No Content if the notification was successfully processed. No response body is required.

Client Errors (HTTP 4xx)

If there is an issue with the request, return a 4xx status code with a response body containing an error code and message.

Example:

{
  "code": "INVALID_SIGNATURE",
  "message": "The signature provided in the X-Signature header is invalid."
}

Server Errors (HTTP 5xx)

If a server error occurs, return a 5xx status code. Osigu will retry up to 10 times with progressive intervals. The response body format should match the example above for 4xx errors.

Security Best Practices

HTTPS Enforcement

Ensure that both sandbox and production endpoints use HTTPS to encrypt communication and protect sensitive information.

IP Whitelisting

Restrict incoming traffic to only Osigu's known IP ranges. These ranges will be shared with you during the integration process.

Signature Mechanism

To ensure the integrity of the payload and verify that the request originates from Osigu, a signature mechanism is used. Each webhook request includes an X-Signature header generated using HMAC SHA-256.

Validating the Signature

1. Retrieve the X-Signature header:
   The signature is sent in the X-Signature header of the webhook request.

2. Compute the signature:
   Use the shared secret key (provided by Osigu) and the raw JSON payload to compute the HMAC SHA-256 hash.

3. Compare signatures:
   Match the computed hash with the value in the X-Signature header. If they do not match, reject the request.

Example in Python

import hmac
import hashlib

# Your secret key
secret_key = b'shared_secret_key'

# The raw JSON body received in the webhook
raw_body = b'{"event":"PRESCRIPTION_CREATED","prescription_id":123456,...}'

# The signature from the header
received_signature = "4a3f215d..."  # Example signature from X-Signature header

# Compute the HMAC SHA-256 signature
computed_signature = hmac.new(secret_key, raw_body, hashlib.sha256).hexdigest()

# Validate the signature
if computed_signature != received_signature:
    raise Exception("Invalid signature")
else:
    print("Signature valid")

This validation ensures that the payload has not been tampered with and that the request originated from Osigu.

Events

Osigu sends webhook notifications for various prescription-related events. Below is a detailed explanation of each event type.

Event Types

Example Payload for Each Event

PRESCRIPTION_CREATED

{
  "event": "PRESCRIPTION_CREATED",
  "prescription_id": 123456,
  "prescription_document_id": "DOC123456ABC",
  "prescription_document_code": "PRESC-987654",
  "type": "PRESCRIPTION",
  "doctor_id": 654321,
  "external_provider_id": "EXT-12345",
  "created_at": "2024-11-13T12:34:56Z"
}

PDF_RENDERED

{
  "event": "PDF_RENDERED",
  "prescription_id": 123456,
  "prescription_document_id": "DOC123456ABC",
  "prescription_document_code": "PRESC-987654",
  "type": "PRESCRIPTION",
  "doctor_id": 654321,
  "external_provider_id": "EXT-12345",
  "created_at": "2024-11-13T12:35:00Z"
}

PDF_SIGNED

{
  "event": "PDF_SIGNED",
  "prescription_id": 123456,
  "prescription_document_id": "DOC123456ABC",
  "prescription_document_code": "PRESC-987654",
  "type": "PRESCRIPTION",
  "doctor_id": 654321,
  "external_provider_id": "EXT-12345",
  "created_at": "2024-11-13T12:36:00Z"
}

EMAIL_SENT

{
  "event": "EMAIL_SENT",
  "prescription_id": 123456,
  "prescription_document_id": "DOC123456ABC",
  "prescription_document_code": "PRESC-987654",
  "type": "PRESCRIPTION",
  "doctor_id": 654321,
  "external_provider_id": "EXT-12345",
  "created_at": "2024-11-13T12:37:00Z"
}

PRESCRIPTION_VOIDED

{
  "event": "PRESCRIPTION_VOIDED",
  "prescription_id": 123456,
  "prescription_document_id": "DOC123456ABC",
  "prescription_document_code": "PRESC-987654",
  "type": "PRESCRIPTION",
  "doctor_id": 654321,
  "external_provider_id": "EXT-12345",
  "created_at": "2024-11-13T12:38:00Z"
}

Notes on Event Handling

To ensure seamless integration and accurate processing of prescription-related events, follow these guidelines when handling webhook notifications from Osigu:

1. Webhook Endpoint Requirements

• Your webhook endpoint must be capable of handling incoming POST requests over HTTPS.
• Validate the signature header as described in the Security Best Practices section to ensure authenticity of the request.
• Your endpoint should return appropriate HTTP status codes based on the request outcome:
  • 204 No Content: Use this code if the notification has been successfully processed.
  • 4xx Error Codes: For client-side errors, such as malformed JSON or failed authentication.
  • 5xx Error Codes: For server-side errors, indicating unexpected issues on your end. Osigu will retry notifications in such cases.

2. Logging and Monitoring

• Log every incoming request payload along with headers for debugging and audit purposes.
• Ensure that logs contain timestamps and unique identifiers such as prescription_id and event.

3. Event Processing

• Handle each event type (PRESCRIPTION_CREATED, PDF_RENDERED, etc.) based on your business logic.
• Use the prescription_id and event attributes to correlate and process events for the same prescription.
• Ensure that idempotency is handled properly to avoid processing the same event multiple times.

4. Error Management

• If your system encounters issues, ensure that appropriate error codes (4xx or 5xx) are returned to Osigu.
• Monitor retry attempts for 5xx errors. Osigu will retry up to 10 times with increasing intervals.

5. Notifications and Alerts

• Set up alerts for critical errors (e.g., repeated 5xx responses or signature validation failures).
• Test your webhook endpoint thoroughly in both sandbox and production environments.

6. Security Best Practices

• Ensure HTTPS is used for all webhook communications.
• Validate the X-Signature header using the mechanism detailed in the Security Best Practices.
• Restrict IP access to your webhook endpoint if possible to allow only Osigu servers.