Webhooks¶

Webhooks are a mechanism for the Nextmv platform to send real-time notifications to your application when certain events occur. They allow you to receive updates about changes in your data or the status of your operations without having to constantly poll the Nextmv Cloud API.

The following events can currently trigger webhooks:

• run.status: triggered when the status of a run changes. E.g., from running to succeeded.

To use webhooks, you should follow these steps:

1. Create a webhook. You must provide an endpoint URL where the Nextmv platform can send the webhook payloads. This URL should be publicly accessible and able to handle incoming HTTP POST requests.

2. Retrieve the secret for the webhook. The secret is used to recompute the HMAC signature of the request to verify its authenticity. In the header of the request sent when the webhook is triggered, we will include the Nextmv-Signature that you can use to check the authenticity of the request. It has the following format:

   Nextmv-Signature: t=UNIX_TIME_IN_SECONDS,v1=HMAC_SHA256_ENCODED_SIGNATURE
   

3. Implement a handler in your service to process the incoming webhook requests. This handler should:

   • Verify the HMAC signature of the request using the secret.
   • Parse the JSON payload of the request.
   • Take appropriate action based on the event type and data received.

   In order to check the authenticity of the request, you need to recompute the HMAC signature using the secret, the payload (the request body), and the timestamp t from the header.

   Here is a simple Python example that shows how to verify the signature:

   import hashlib
   import hmac
   
   
   def check_signature(payload: bytes, t: int, signature: str, secret: str) -> bool:
       """
       Recompute the signature of the payload using the secret and the timestamp. Compare the
       recomputed signature with the signature provided in the header.
       """
   
       mac = hmac.new(secret, digestmod=hashlib.sha256)
       mac.update(str(t).encode())
       mac.update(b".")
       mac.update(payload)
       recomputed_signature = mac.hexdigest()
       return recomputed_signature == signature
   

The request body of a triggered event look like this, according to the event type:

{
"event_type": "run.status",
"api_version": "2024-03-04",
"data": {
    "run_id": "test-run-id",
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2024-03-21T13:19:34Z",
    "duration": 1000,
    "input_size": 1000,
    "output_size": 1000,
    "error": null,
    "application_id": "app_id",
    "application_instance_id": "app_instance_id",
    "application_version_id": "app_version_id"
}
}

Webhooks record conversations. A conversation is the request to and the response from the registered endpoint.