Events and Webhooks

Webhooks provide a powerful mechanism to receive real-time notifications about events occurring within the PCE. By configuring webhook endpoints, your platform can eliminate the need for constant API polling,

How Webhooks work?

• Webhooks utilize HTTP callbacks to send push notifications to pre-configured endpoints.
• When an event related to a PCE entity occurs, a JSON payload containing details about the event is sent as a POST request to your specified webhook URL.

Important Notes

• Enable/Disable: Webhooks can be enabled or disabled at any time through the platform.
• Retry Mechanism: The system will attempt to deliver a webhook notification up to 5 times if a successful acknowledgment (HTTP 2xx status code) is not received from your configured endpoint.
• Endpoint Blocking: After 5 unsuccessful attempts, the system will block the endpoint. You can re-enable the endpoint once the issue on your end is resolved.

Setup for Webhook Subscription

• To begin receiving webhook notifications, you need to configure your desired endpoint in the PM portal.
• Navigate to the Webhooks Section: In the PM portal, go to the "Webhooks" section.
• Enter Endpoint URL: Enter the https URL you wish to configure as your webhook endpoint. This URL will receive POST requests with JSON payloads from PCE.
• Create Webhook: Click "Create" to finalize the webhook configuration.

Subscription Confirmation

Upon creation, a subscription confirmation message will be sent to the configured URL. This is a crucial step to verify ownership and readiness of your endpoint.

{
    "Type": "SubscriptionConfirmation",
    "MessageId": "e7caa54f-7380-42ff-bf41-1a847b5db5a9",
    "Token": "2336412f37fb687ff41a9668e",
    "TopicArn": "arn:aws:sns:us-east-1:9853074181:test-topic1",
    "Message": "You have chosen to subscribe to the topic arn:aws:sns:us-east-1:985323074181:test-topic1.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
    "SubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-east-1:985323074181:test-topic1&Token=2336440d7df41a9668e",
    "Timestamp": "2024-05-15T08:53:04.873Z",
    "SignatureVersion": "1",
    "Signature": "KwtRZ0gNGtkBIeMMzUkPVh/Ail3173vqyffdpebj1qHe1xVx0EOIM3tx3w==",
    "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-60eadc530605d63b8e62a523676ef735.pem"
}

Steps to Confirm Subscription

• Extract SubscribeURL: From the received subscription confirmation message, extract the value of the SubscribeURL field.
• Make a GET Call: Make an HTTP GET request to the extracted SubscribeURL. This action confirms your subscription and signals to PCE that your endpoint is ready to receive event notifications.

Handling Authentication for Webhook Endpoints
If your configured webhook endpoint requires authentication (e.g., Basic Authentication), follow these additional steps when receiving the subscription confirmation message:

1. Return HTTP 401 (First Response): Upon receiving the SubscriptionConfirmation message, your endpoint should first return an HTTP 401 Unauthorized status code.
2. Include WWW-Authenticate Header: In the 401 response, include the WWW-Authenticate = Basic header. This indicates to the system that your endpoint requires Basic Authentication.
3. Proceed with GET Call toSubscribeURL: After sending the 401 response with the WWW-Authenticate header, proceed with making the GET call to the SubscribeURL as described above.

Once the subscription is successfully confirmed, you will begin receiving webhooks at your configured endpoint, typically within 1-1.5 hours.

Sample Code for Handling Subscription Confirmation
The following Node.js example demonstrates how to handle SNS (Simple Notification Service) messages, including subscription confirmation and authentication. While the example uses x-amz-sns-message-type headers, the core logic for confirming the SubscribeURL and handling authentication remains relevant for PCE webhooks.

// Endpoint to handle SNS messages
app.post('/sns-endpoint', authMiddleware, (req, res) => {
    // Validate header (replace with your actual authentication logic)
    const authHeader = req.headers['authorization'];
    if (!authHeader) {
        res.setHeader('WWW-Authenticate', 'Basic');
        return res.status(401).send('Authentication required.');
    }

    // Handle SNS message type (adapt for PCE webhook message types if different)
    const messageType = req.headers['x-amz-sns-message-type']; // Or a similar header for PCE
    if (messageType === 'SubscriptionConfirmation') {
        // Handle subscription confirmation
        const confirmUrl = req.body.SubscribeURL;
        console.log(`Confirming subscription at URL: ${confirmUrl}`);

        // IMPORTANT: In a real application, you would make an HTTP GET request
        // to the confirmUrl to truly confirm the subscription.
        // For simplicity, this example just logs it.
        // Example using a library like 'axios' or 'node-fetch':
        // axios.get(confirmUrl)
        //   .then(() => console.log('Subscription confirmed successfully!'))
        //   .catch(error => console.error('Error confirming subscription:', error));

    } else if (messageType === 'Notification') {
        // Handle regular event notifications (adapt for PCE event types)
        const message = req.body.Message;
        console.log(`Received message: ${message}`);
        // Process the webhook payload based on the event type
    }

    // Acknowledge receipt of the message
    res.status(200).send('Message received.');
});