Webhooks

Introduction

Webhooks allow you to connect your hosted agency tenant with your internal service. They can be used to notify you when an agent message is processed by your agent. Webhooks are scoped to a tenant. You can register up to 5 notification webhooks for each tenant.

There are two types of webhooks

  • Notification webhooks - used to setup alerts and notifications after an agent message of any type is processed
  • Endorser webhooks (Coming soon) - used to call another running agent to sign a request that will be submitted to the ledger.

There are four types of webhook agent messages

  • New Connection
  • Credential Request
  • Verification
  • New Inbox Message

Each type will have an associated object_id that is a unique string identifier to the object from which the event occurred. Within the data field, there will be a connection_id field that corresponds to the connection from which the event occurred. note that in the event of a new_connection, the object_id and the data.connection_id will be identical.

{
"message_type": "new_connection" OR "credential_request" OR "verification" OR "new_inbox_message",
"object_id": connection_id OR credential_id OR verification_id OR message_id,
"data": {
"connection_id": connection_id
}
}

To use endorser signing webhooks you must setup your tenant for delegated signing during registration.

Create a notification webhook

To create new notification webhook, use the POST /webhooks endpoint, or use the service client as described below.

const result = await client.createWebhook({
webhookParameters: {
"url": "<your_endpoint_url>",
"type": "Notification"
}
});
console.log("Webhook created: " + result.id);

API Reference

POST /webhooks​

Setup your webhook endpoint

To setup a listening webhook in your service, your endpoint must listen to POST http message. The body of the request will have the following parameters. The content of the body will be set to application/json.

POST 'https://your/webhook/url'
Content-Type: application/json
Body:
{
"message_type": "new_connection",
"object_id": "00000000",
"data": {
"param1": "value1",
"param2": "value2"
// ...
}
}

List registered webhooks

To get a list of all registered webhooks, call the GET /webhooks endpoint or use the service client for your platform.

const webhooks = await client.listWebhooks();

API Reference

GET /webhooks

Enable or disable a webhook

You can disable some webhooks to temporarily prevent them from being invoked. Only webhooks that are enabled will be called by your hosted agent.

To disable a webhook, call the PUT /webhooks​/{webhookId}​/disable endpoint. Similarly, to enable a webhook call the PUT /webhooks​/{webhookId}​/enable endpoint or use the service clients as described below.

// Disable a webhook
await client.disableWebhook(webhookId);
// Enable a webhook
await client.enableWebhook(webhookId);

API Reference

PUT /webhooks​/{webhookId}​/enable

PUT /webhooks​/{webhookId}​/disable

Remove a webhook

To remove a webhook permanently, call the DELETE /webhooks/{webhookId} endpoint or use the service clients as described below.

await client.removeWebhook(webhookId);

Parameters

  • webhookId [string required] - The webhook identifier

API Reference

DELETE /webhooks​/{webhookId}​

Notification webhooks are used to setup alerts and notifications after an agent message of any type is processed by your hosted agent. Webhooks can be setup in any runtime that can listen to incoming HTTP traffic.