Skip to content

Creating a webhook through API

To create a webhook in Truto, call the webhook create endpoint.

An example webhook create request would look something like,

curl --location 'https://api.truto.one/webhook' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <api_token>' \
--data '{
    "target_url": "https://webhook.site/6a7cc86e-9286-4be8-ba79-bcd8dfdbeee1",
    "is_active": true,
    "event_types": ["integrated_account:created"]
}'

In the example request above,

  • target_url is the webhook endpoint where a POST request with the webhook payload as the request body will be made.
  • is_active is an optional field which specifies if the target_url should receive webhook events.
  • event_types is an array of webhook event types that the target_url should receive data for. It is optional and if not mentioned in the request, then the target_url will receive data for all webhook event types.

The request should yield a response like so,

{
    "id": "b6d29b9b-3d9d-44fd-aa77-512fd83b28c1",
    "target_url": "https://webhook.site/6a7cc86e-9286-4be8-ba79-bcd8dfdbeee1",
    "secret": "6e17561c-a20c-44ce-b8b5-caff0bf786fe",
    "is_active": true,
    "environment_id": "ac15abdc-b38e-47d0-97a2-69194017c199",
    "event_types": ["integrated_account:created"],
    "created_at": "2023-06-15T14:40:03.000Z",
    "updated_at": "2023-06-15T14:40:03.000Z"
}
  • event_types lists the subscribed event types. It is ["all"] when the request did not specify any.
  • secret is returned only in this response. Fetching or listing webhooks later does not include it, so store it securely now. It must be used to verify the webhook event's signature, which can be found X-Truto-Signature header of the request body of the webhook event. The secret is unique to each webhook that you create. See verifying webhook events.

Send test event

To send a test event to the webhook, call the webhook send test event endpoint.

curl --location 'https://api.truto.one/webhook/test' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <api_token>' \
--data '{
    "id": "b6d29b9b-3d9d-44fd-aa77-512fd83b28c1",
    "event_type": "integrated_account:created"
}'
  • id is the ID of the webhook to send the test event to.
  • event_type is optional and defaults to integrated_account:created. It can be any event type from the list of webhook event types except all.
  • integrated_account_id is optional. When set, the test payload is built from that integrated account, which must belong to the webhook's environment.
  • payload is an optional object merged into the generated test payload.

A successful test returns the event that was sent,

{
    "success": true,
    "event_type": "integrated_account:created",
    "payload": { ... }
}

If your endpoint responds with a non-2XX status code, the request fails with a 500 error whose message includes the status code and response body your endpoint returned.

API Reference

Refer Webhooks API reference for all the endpoints.