# IWebhookStore

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.iwebhookstore/
> Summary: IWebhookStore: The store for webhook subscriptions and delivery history.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

The store for webhook subscriptions and delivery history.

```csharp
public interface IWebhookStore
```

## Remarks

**Delivery guarantee — AT-LEAST-ONCE.** A row created by
[IWebhookStore.CreateDeliveryAsync](/api/tracon.iwebhookstore/#Tracon_IWebhookStore_CreateDeliveryAsync_Tracon_WebhookDelivery_System_Threading_CancellationToken_) can be attempted more than once: the
delivery job (an `IJobHandler`, itself at-least-once — see
`IJobHandler.ExecuteAsync`'s own remarks) retries a failed HTTP POST
against the SAME [WebhookDelivery.Id](/api/tracon.webhookdelivery/#Tracon_WebhookDelivery_Id), and each attempt is
recorded with its own [IWebhookStore.RecordDeliveryResultAsync](/api/tracon.iwebhookstore/#Tracon_IWebhookStore_RecordDeliveryResultAsync_Tracon_WebhookDeliveryResult_System_Threading_CancellationToken_) call rather
than overwriting the last one. This store neither deduplicates nor
collapses those attempts — it is the recipient's job to do so. Every
attempt, the original and every retry, carries the SAME delivery id in the
`X-Tracon-Delivery` header; a recipient that wants exactly-once
processing MUST deduplicate on that header's value.

## Methods

### <a id="Tracon_IWebhookStore_CreateDeliveryAsync_Tracon_WebhookDelivery_System_Threading_CancellationToken_"></a> CreateDeliveryAsync\(WebhookDelivery, CancellationToken\)

Creates a delivery record.

```csharp
ValueTask<WebhookDelivery> CreateDeliveryAsync(WebhookDelivery delivery, CancellationToken cancellationToken = default)
```

#### Parameters

`delivery` [WebhookDelivery](/api/tracon.webhookdelivery/)

The delivery.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[WebhookDelivery](/api/tracon.webhookdelivery/)\>

The created record.

### <a id="Tracon_IWebhookStore_DeleteSubscriptionAsync_System_String_System_String_System_Threading_CancellationToken_"></a> DeleteSubscriptionAsync\(string, string, CancellationToken\)

Deletes a subscription and its delivery history.

```csharp
ValueTask<bool> DeleteSubscriptionAsync(string tenantId, string name, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant identifier.

`name` [string](https://learn.microsoft.com/dotnet/api/system.string)

The subscription name.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[bool](https://learn.microsoft.com/dotnet/api/system.boolean)\>

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) if the delete happened.

### <a id="Tracon_IWebhookStore_FindForEventAsync_System_String_System_String_System_Threading_CancellationToken_"></a> FindForEventAsync\(string, string, CancellationToken\)

Fetches all enabled subscriptions subscribed to a specific event.

```csharp
ValueTask<IReadOnlyList<WebhookSubscription>> FindForEventAsync(string tenantId, string eventType, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant identifier.

`eventType` [string](https://learn.microsoft.com/dotnet/api/system.string)

The event name.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[WebhookSubscription](/api/tracon.webhooksubscription/)\>\>

The matching subscriptions. An empty list if none.

### <a id="Tracon_IWebhookStore_GetDeliveryAsync_System_Guid_System_Threading_CancellationToken_"></a> GetDeliveryAsync\(Guid, CancellationToken\)

Fetches a single delivery record.

```csharp
ValueTask<WebhookDelivery?> GetDeliveryAsync(Guid deliveryId, CancellationToken cancellationToken = default)
```

#### Parameters

`deliveryId` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The delivery identifier.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[WebhookDelivery](/api/tracon.webhookdelivery/)?\>

The record; [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) if it does not exist.

### <a id="Tracon_IWebhookStore_GetSubscriptionAsync_System_String_System_String_System_Threading_CancellationToken_"></a> GetSubscriptionAsync\(string, string, CancellationToken\)

Fetches a single subscription by name.

```csharp
ValueTask<WebhookSubscription?> GetSubscriptionAsync(string tenantId, string name, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant identifier.

`name` [string](https://learn.microsoft.com/dotnet/api/system.string)

The subscription name.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[WebhookSubscription](/api/tracon.webhooksubscription/)?\>

The subscription; [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) if it does not exist.

### <a id="Tracon_IWebhookStore_ListSubscriptionsAsync_System_String_System_Threading_CancellationToken_"></a> ListSubscriptionsAsync\(string, CancellationToken\)

Lists a tenant's subscriptions.

```csharp
ValueTask<IReadOnlyList<WebhookSubscription>> ListSubscriptionsAsync(string tenantId, CancellationToken cancellationToken = default)
```

#### Parameters

`tenantId` [string](https://learn.microsoft.com/dotnet/api/system.string)

The tenant identifier.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[WebhookSubscription](/api/tracon.webhooksubscription/)\>\>

The subscriptions.

### <a id="Tracon_IWebhookStore_QueryDeliveriesAsync_Tracon_WebhookDeliveryQuery_System_Threading_CancellationToken_"></a> QueryDeliveriesAsync\(WebhookDeliveryQuery, CancellationToken\)

Lists delivery history. The newest record is returned first.

```csharp
ValueTask<IReadOnlyList<WebhookDelivery>> QueryDeliveriesAsync(WebhookDeliveryQuery query, CancellationToken cancellationToken = default)
```

#### Parameters

`query` [WebhookDeliveryQuery](/api/tracon.webhookdeliveryquery/)

The filter.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[WebhookDelivery](/api/tracon.webhookdelivery/)\>\>

The records.

### <a id="Tracon_IWebhookStore_RecordDeliveryResultAsync_Tracon_WebhookDeliveryResult_System_Threading_CancellationToken_"></a> RecordDeliveryResultAsync\(WebhookDeliveryResult, CancellationToken\)

Writes a delivery attempt's result.

```csharp
ValueTask RecordDeliveryResultAsync(WebhookDeliveryResult result, CancellationToken cancellationToken = default)
```

#### Parameters

`result` [WebhookDeliveryResult](/api/tracon.webhookdeliveryresult/)

The result.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask)

The completion task.

### <a id="Tracon_IWebhookStore_RecordSubscriptionOutcomeAsync_System_Guid_System_Boolean_System_Int32_System_DateTimeOffset_System_Threading_CancellationToken_"></a> RecordSubscriptionOutcomeAsync\(Guid, bool, int, DateTimeOffset, CancellationToken\)

Updates a subscription's consecutive-failure counter, and disables the
subscription if the threshold is exceeded.

```csharp
ValueTask<bool> RecordSubscriptionOutcomeAsync(Guid subscriptionId, bool succeeded, int disableThreshold, DateTimeOffset updatedAt, CancellationToken cancellationToken = default)
```

#### Parameters

`subscriptionId` [Guid](https://learn.microsoft.com/dotnet/api/system.guid)

The subscription identifier.

`succeeded` [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

Whether the most recent delivery succeeded.

`disableThreshold` [int](https://learn.microsoft.com/dotnet/api/system.int32)

The subscription is disabled after this many consecutive failures.

`updatedAt` [DateTimeOffset](https://learn.microsoft.com/dotnet/api/system.datetimeoffset)

The update time (UTC).

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[bool](https://learn.microsoft.com/dotnet/api/system.boolean)\>

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) if the subscription was disabled during this call.

### <a id="Tracon_IWebhookStore_SaveSubscriptionAsync_Tracon_WebhookSubscription_System_Threading_CancellationToken_"></a> SaveSubscriptionAsync\(WebhookSubscription, CancellationToken\)

Creates or updates a subscription.

```csharp
ValueTask<WebhookSubscription> SaveSubscriptionAsync(WebhookSubscription subscription, CancellationToken cancellationToken = default)
```

#### Parameters

`subscription` [WebhookSubscription](/api/tracon.webhooksubscription/)

The subscription.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[WebhookSubscription](/api/tracon.webhooksubscription/)\>

The saved subscription.

#### Remarks

[WebhookSubscription.ConsecutiveFailures](/api/tracon.webhooksubscription/#Tracon_WebhookSubscription_ConsecutiveFailures) is written as the
subscription carries it, not kept from the stored row. The management API
saves it as zero, so a subscription disabled for failing gets its whole
threshold back once it is fixed and enabled again.